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Preface 


The VMS Workstation Software Video Device Driver Manual provides a 
programmer with the necessary information for writing applications that 
manipulate the QVSS and QDSS drivers. 


It is structured to serve as both a tutorial manual that will bring an 
experienced programmer up to speed on driver concepts and as a reference 
manual that can be used for quick reference during actual application 
programming. 


QIOs and system routines used when you program to the driver are 
provided in reference form. Data types used to program to the drivers are 
illustrated in the reference sections, and all the data types are summarized 
in two data-type appendixes. 





Intended Audience 


The information contained in this manual is for experienced graphics 
programmers or systems programmers who are writing applications directly 
to the driver. 





Document Structure 


This manual has the following structure: 


e Chapter 1 describes concepts and terms needed to understand 
programming to the driver interface. 


¢ Chapter 2 describes how to perform driver interface tasks that are 
common to both the QVSS and QDSS systems. 


e Chapter 3 describes the common QVSS/QDSS QIO interface. 
e Chapter 4 describes the QDSS-specific QIO interface. 


e Chapter 5 describes how to use the Drawing Operation Primitive 
interface. 


e Appendix A describes all QVSS/QDSS common data types. 

¢ Appendix B describes all QDSS-specific data types. 

e Appendix C describes all multiplane writing modes. 

e Appendix D contains a full QVSS driver example. 

e Appendix E contains macros used to construct keyboards. 

e Appendix F contains macros used to construct compose tables. 

e Appendix G contains the default three-stroke compose table macros. 
e Appendix H contains the $QIO system service description. 


e Appendix I contains the DEC multinational character set table. 


Preface 


e Appendix J contains the ISO Latin NR 1 supplemental character set. 





Associated Documents 
The following VMS manuals are related to this manual: 
e VMS Workstation Software Graphics Programming Guide 
e VMS Workstation Software User’s Guide 
e VMS User’s Guide 





Conventions 


This manual uses the following conventions in displaying the syntax 
requirements of user input to the system and in displaying examples: 


Conventions Meaning 


RETURN key The RETURN key is not always shown in formats and 
examples. Assume that you must press RETURN 
after typing a command or other input to the system 
unless instructed otherwise. 


CTRL key The word CTRL followed by a slash followed by 
a letter means that you must type the letter while 
holding down the CTRL key. For example, CTRL/B 
means hold down the CTRL key and type the letter B. 


Lists When a format item is followed by a comma and 

an ellipsis (, ...), you can enter a single item ora 
number of those items separated by commas. When 
a format item is followed by a plus sign and an ellipsis 
(+ ...), you can enter a single item or a number of 
those items connected by plus signs. If you enter a 
list (more than one item), you must enclose the list in 
parentheses. A single item need not be enclosed in 


parentheses. 
Optional items An item enclosed in square brackets ({]) is optional. 
Key Symbols In examples, keys and key sequences appear as 
symbols such as [PF2| and | CTRL/Z}. 





Ellipsis . A vertical ellipsis indicates that some of the format or 
: example is not included. 


Delete Key The key on the VT200 series terminal keyboard 
_that performs the DELETE function is labeled <<x]. 
Assume that DELETE in text and examples refers to 
both the VT100 and VT200 series delete keys. 


Examples Examples show both system output (prompts, 
messages, and displays) and user input. User input 
is printed in red. 
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1.1 


Video Device Driver Introduction 


This chapter introduces the concepts and terms that describe how to write 
an application to interact with the QVSS and QDSS video device drivers. 


This chapter describes the following topics: 
e The two available video device drivers (QVSS and QDSS). 


¢ How to determine which programming interface your application 
should address. (Your application might not need to write to a device 
driver.) 


e¢ How the two drivers address the screen. 

e How the drivers use memory. 

¢ How an application accesses a driver. 

Some of the concepts and terms described in the following sections apply 


to both drivers, while others are specific to one driver. The manual clearly 
notes sections that describe specific concepts. 





Overview of the Drivers 


A VAXstation can have one of the following two video device drivers: 
e QVSS-QBus Video Subsystem 
e QDSS-QBus Device Subsystem 


Although both drivers allow you to create graphics applications with 
VAXstation features, each driver requires unique hardware. Thus, a 
VAXstation can be configured with either a QVSS driver or a QDSS driver 
but not both. 


The device drivers provide a common interface to VAXstation hardware 
functions such as manipulating memory and writing to the screen. By 
using a common interface, applications can guarantee that the hardware 
is accessed uniformly. All VAXstation software uses the driver to access 
hardware, either directly or indirectly. Figure 1-1 illustrates the layered 
relationship of applications, VAXstation software, device driver, and 
VAXstation hardware. 
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Figure 1-1 The Driver Interface 
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.1.1. Driver Differences 


The primary differences between the QVSS driver and the QDSS driver 
are: 


e Use of color 
e Use of global sections 
¢ Method of bitmap manipulation 


e Ability to provide alternate windowing systems 


Table 1-1 lists device driver capabilities. 


Table 1-1 Device Driver Differences 


Driver 
Feature QVSS QDss 
Color Bitonal Gray-scale, color 
Memory One-plane Multiplane 
Bit Manipulation Direct DOPs 
Alternate Windowing Available Not available 
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Color 


The QVSS device driver is designed for use with a one-plane memory 
system. It is therefore restricted to the use of black and white images. 


The QDSS device driver is designed for use with multiplane memory 
systems, so the QDSS driver draws color and gray-scale images. 


Bitmap Manipulation 


The QVSS driver supports only direct bitmap manipulation. If you write an 
application to the QVSS driver, your application is completely responsible 
for drawing to the bitmap. 


The QDSS driver provides drawing operation primitives (DOPs) that make 
drawing to the bitmap easier and faster. DOPs use additional multiplane 
hardware to accelerate drawing. 


Alternate Windowing 


The QVSS driver provides a way to alternate between the UIS windowing 
system and a windowing system of your own design. When you use an 
alternate windowing system, both windowing systems share video memory. 


The QDSS driver does not currently provide a way to alternate between 
windowing systems; it supports only one windowing system at a time. 





1.2 Choosing an Interface 


When you write an application, determine which level of interface your 
application should address. As shown in Figure 1-1, your application 

can address the system at the UIS level, the driver level, or the hardware 
level. For each successive level downward, your application increases its 
degree of control but increases its difficulty and the amount of work it must 
perform. 


UIS and UISDC Interface 


UIS, the VAXstation graphics operating system, provides a basic set of 

graphic primitive, color, and windowing routines to use when you write 
high-level graphics applications. UIS routines use a device-independent 
world coordinate system. 


If your application requires direct access to display coordinates, it can use 
UISDC routines, which allow you to manipulate primitives in a device- 
dependent manner. The UIS and UISDC routines are described in the 
VMS Workstation Software Graphics Programming Guide. 


If the UIS interface provides all the necessary functionality for your 
application, address the UIS interface. 


Driver Interface 


Your application can bypass the UIS/UISDC interface and manipulate the 

driver directly. This feature allows you to create graphics packages tailored 
to your specific needs. For example, you can design your own windowing 
system, or you can provide your own drawing routines. 
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Hardware Interface 


You can bypass both the UIS interface and the driver interface and directly 
address the hardware. If your application does not need a windowing 
system, consider writing directly to the hardware. How to address 

the hardware directly is beyond the scope of this manual. Refer to the 
hardware documentation for information about the hardware interface. 





3 How the Drivers Work 


Before you can write to the driver interface, you should understand the 
concepts and terms explained in this section. 


.3.1. Defining Regions on the Screen 


Both drivers address rectangular portions of the screen called regions. The 
QDSS driver accesses regions of the screen as viewports. Section 1.3.10 
describes viewports. Your application uses driver interface QIOs to define 
addressable screen regions. 


For the driver to define a region, your application must associate the region 
with a unique channel. The channel provides a logical path that connects 
an application to the device driver. Before you define a region, call the 
$ASSIGN system service to obtain a unique channel number for the region. 
(The VAX/VMS System Services Reference Manual has more information on 
$ASSIGN.) 


When your application defines a region, it associates the region with one of 
the following events: 


e Cursor pattern 

e Keyboard input 

e Pointer button transition 
e Pointer movement 


¢ Viewport (QDSS only) 


The QIO you use to define the region determines the type of event the 
driver associates with the region. For example, if you want the driver to 
associate a region with button transitions, define the region with the Enable 
Button Transition QIO. To cause an action to occur when the event is 
detected in that region, include the address of an AST action routine as 

a parameter of the region-defining QIO. For example, you can define a 
region, associate it with a button transition, and specify that the region be 
erased when the driver detects the transition. 


The driver detects when an event occurs and ensures that the proper action 
takes place. Section 1.3.4 describes how the drivers manage regions and 
events. 
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1.3.2 Driver Communication Mechanisms 


An application can use a QIO interface to access either driver. An 
application can also use a mechanism called the request queue to access 
the ODSS driver. 
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QIO Interface 

The QIO interface is the method of access common to most drivers. The 
QVSS and QDSS drivers provide a number of QIOs that perform the 
following driver-specific functions: 


e¢ Screen initialization 
e Pointer movement region definition 


e Bitmap copy performance 


While the QIO interface is common to both drivers, some QIOs are 
QDSS-specific. Any driver QIO can be used with the QDSS driver, (see 
Chapter 4), while the QIOs that apply to both the QVSS and QDSS drivers 
are a subset of the entire QIO interface (see Chapter 3). 


Most QIOs are input functions. When you call them, you typically 
specify IO$_SETMODE as the function parameter. In these QIOs, the 
P1 parameter actually serves as the distinguishing function code. 


The remaining QIOs are output functions. When you call them, you 
typically specify IO$_SENSEMODE as the function parameter. In these 
QIOs, the P1 parameter actually serves as the distinguishing function code. 


Although the QIO interface permits a wide range of functions, some 

are grouped together in functional categories. The following sections 
contain general descriptions of those categories. (See Chapters 3 and 4 for 
complete descriptions of all QIOs.) 


Tracking Associated Events and Regions 


Several input QIOs permit an application to construct list entries. To 
associate regions with events, the QVSS and QDSS drivers maintain one 
list for each event type. Typically, when you define a region, you use an 
input QIO that passes the driver the following information: 


e¢ Region description 
e Associated event 


e Address of an AST routine that defines the action to take when the 
event occurs 


The driver uses this information to construct a list entry, which it places 
on the appropriate list. When an event occurs, the driver searches the lists 
and triggers the AST indicated by the appropriate list entry. Section 1.3.4 
explains how the driver constructs and manages lists. 


Returning System Information 


Your application gets information from the system with output QIOs. The 
Get System Information QIO returns the system information block, which 
describes the state of the system in: 


e Dimensions (and subdivisions) of video memory 
¢ Current pointer position 


e Current button status 
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1.3.2.2 


The QDSS system information block contains all the same fields as 

the QVSS information system block, but includes additional fields. 
Appendices A and B illustrate and describe the structure of both system 
blocks: 


¢ QVB—OQVSS system information block 
¢ QDB—QDSS system information block 


You can also use the Get Keyboard Characteristics QIO to inquire about 
the characteristics of the current keyboard. 


On QDSS systems only, you can obtain a viewport ID for use in subsequent 
operations, as well as color map information. See Section 1.3.10 for 
information about viewports. 


Queue Manipulation 
This section applies only to QDSS systems. 


To manipulate the QDSS-specific queues, you use three QDSS-specific 
output QOlOs: 


e Request queue 
e Return queue 


¢ Deferred queue 


These QIOs permit an application to stop and start processing queues. The 
request queue is briefly described in the next section. A full description of 
the three queues appears at the end of this chapter. 


Request Queue interface 
This section applies only to QDSS systems. 


The request queue interface, which allows your application to perform 
drawing operations and to manipulate queues, requires less overhead than 
the QIO interface. 


To operate the request queue, your application uses drawing operation 


primitives (DOPs), structures that contain the data needed to perform a 


drawing operation. Your application submits DOPs to the request queue 
for execution. The request queue is a double-linked list of all the DOPs 
waiting for execution. DOPs are placed on the queue in execution (drawing) 
order. 


Section 1.3.11 describes the QDSS-specific queues in detail. Chapter 5 
describes how to use DOPs. 


1.3.3 How Drivers Use Memory 


To write to the screen, an application actually writes to video memory. The 
driver then maps the video memory to the screen. To understand how to 
program to the drivers, you must understand how the drivers use memoty. 


1.3.3.1 


NOTE: 
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How QVSS Uses Video Memory 

The VAXstation display area is 1024 x 864 pixels. The full QVSS video 
memory is a 1024- x 2048-bit block of memory or, to correspond to the 
screen, 2048 lines of 1024 pixels. To map lines of video memory to lines 
on the screen, QVSS uses a data structure called the scanline map. 


The scanline map is a contiguous-word index into video memory, which 
indexes the entire screen display area (864 lines). Each entry in the scanline 
map is a 0-relative, 16-bit word value that functions as an index into video 
memory. The first entry in the scanline map locates the first line of the 
screen display; the second entry contains the second line, and so forth. 
For each bit set on an indexed line of video memory, the driver sets a 
corresponding pixel on the display screen. 


However, since a maximum of 864 lines of video memory can display at a 
time and total video memory is 2048 lines, QVSS video memory is referred 
to in two sections: 


e Onscreen memory—Any portion of video memory currently displayed. 
Since the largest VAXstation display is 864 lines, that is the maximum 
size of onscreen memory. 


e Offscreen memory—The 1184 undisplayed lines of video memory. 


You use offscreen memory to store images or fonts that are not currently 
being displayed, as well as to handle occlusion (see Section 1.3.9). 


On a VAXstation 2000 monochrome monitor, system video memory is 
slightly different. One screen of video memory is available (1024-bit x 864- 
bit). Also, the hardware scanline map is not available. The system always 
displays 864 scanlines of video memory with the first scanline starting at 
the first byte of video memory. Therefore, you cannot change the scanline 
order. 


Figure 1-2 illustrates the layout of QVSS memory. 
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Figure 1-2 QVSS Video Memory and Scanline Map 
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Hardware Cursor 


The screen cursor is defined by a separate block of hardware memory as 
follows: 


e QVSS single-plane cursor systems—16 x 16 bits 
¢ QDSS multiplane cursor systems—16 x 32 bits 


This block stores the bitmap image of the cursor pattern. It is not part of 
video memory. 


The driver uses the hardware to overlay the video signal sent to the screen 
(see Figure 1-2). This arrangement eliminates the need for a save and 
restore operation in video memory each time the cursor moves or a write 
to video memory occurs. Section 2.8 describes how to define cursor 
patterns. 


Scanline Map 


Note that the scanline map need not index consecutive lines of video 
memory. That is, an object can be represented in nonconsecutive lines 
in video memory (when there is not enough consecutive memory), yet 
appear on consecutive lines on the screen. Figure 1-3 illustrates how the 
scanline map properly maps to the screen two objects represented in 
nonconsecutive memory. 


1.3.3.2 
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Figure 1-3 Scanline Map Mapping Nonconsecutive Memory 
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Accessing QVSS Video Memory 


QOVSS permits direct bitmap access, such that an application can set bits 
directly in video memory. 


An application can write to QVSS video memory with any suitable 
computer language (FORTRAN, MACRO, and so forth). However, before 
it writes to video memory, an application must issue the Get System 
Information QIO to obtain the QVSS system block (QVB), which contains 
all the information necessary to write to video memory. See Appendix A 
for a complete description of the QVB. 


An application should issue a QVB request for each process. Because the 
address of the system block does not change, a process can obtain the 
QVB address once and continue to reference fields in the QVB until the 
process terminates. 


How QDSS Uses Video Memory 

The largest possible VAXstation display is a 1024- by 864-pixel area, or 
864 lines that are 1024 pixels in length. The full QDSS video memory is a 
2048- by 1024-pixel block of memory or, to correspond to the screen, 2048 
lines that are 1024 pixels in length. QDSS maps video memory directly 
to the screen. In the case of the largest display, it maps the first 864 lines 
of video memory to the screen. This portion of video memory is called 
onscreen memory. 


V4.1—June 1989 1-9 


Video Device Driver Introduction 


The remaining 1184 lines of video memory are called offscreen memory. 
Offscreen memory handles occlusion. The offscreen portion of the video 
memory is further divided into the following fixed-length sections: 


¢ Scrolling save area 
e Reserved area 
e Free_1 area 


e Bitmap storage area 


Figure 1-4 illustrates the layout of QDSS memory and shows relative 
coordinates for the beginning and end of each area. 


Figure 1-4 QDSS Video Map 
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(0,0) (1023, 0) 
Scrolling Save Area 
(0, -28) 28 lines (1023, -28) 
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Free_1 Area 
1080 lines 


Bitmap Storage Area 
70 lines 


(0,-1114) (1023,- 1114) 


(0,- 1184) (1023, - 1184) 


Note that the lower left corner of onscreen memory is assigned the 
coordinate (0,0). This corresponds to the lower left corner of the display. 
(All viewports are defined relative to this base.) Therefore, any coordinate 
with a negative Y element is in offscreen memory. 


Scroll Area 


The driver uses the scroll area to process downward scrolls. This area is 
reserved for the driver and cannot be accessed by the application. 


| Free_1 Area 


Free_1 is the largest area of free memory. An application can use this 
memory for any operations. 
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Bitmap Storage Area 

The driver uses this area to store bitmaps: 
e Fonts 

e Images 


e §©Pattern fills 


The area has a 70-line by 1024-bit block of memory for each memory plane on the system. To 
accommodate more fonts in memory, some planes partition the 70-line blocks into two 35-line 
sections. An application uses this area to load any defined bitmaps stored in VAX memory. 


NOTE: 


Use the Load Bitmap QIO or the UISDC$LOAD_BITMAP routine to load 
the information in VAX memory into the bitmap storage area. 


If a bitmap does not fit into the bitmap storage area, the application must 
partition the information into one 70-line section for a single-plane image 
or two 35-line sections for multiplane images. 


QDSS Video Memory Access 


QDSS does not permit direct bitmap access. Use the DOP interface to 
draw to video memory, and use the Read Bitmap and Write Bitmap QIOs 
to copy images to video memory. 


Viewports—The QDSS driver must direct all operations to the screen 
via a viewport. An application can create viewports or use the default 
systemwide viewport (the full screen). See Section 1.3.10 for more 
information about viewports. 


Exclusive Bitmap Access—Your application might require exclusive bitmap 
access to video memory. When you perform an exclusive-access operation, 
no other operation should access onscreen memory. Since the QDSS 
driver controls onscreen memory access, an application must always notify 
the driver of a pending exclusive bitmap operation. 


Bitmap Transfers—The QDSS driver can perform three types of bitmap 
transfers: 


e VAX memory-to-bitmap 
¢ Bitmap-to-VAX memory 
¢ Bitmap-to-bitmap 


Drivers use the QIO interface to execute transfers, which require exclusive bitmap access for 


synchronization. 


QDB—An application can issue the Get System Information QIO to obtain 
the QDSS system block (QDB). The QDB contains information about video 
memory that an application needs to manipulate video memory. See 
Appendix B for a complete description of the QDB. 
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1.3.4 Howthe Drivers Track Screen Events 


To track events that occur on the screen, the QVSS and QDSS drivers keep 
a list for each of the following event types: 


e Cursor pattern change 

e Pointer button transition 

e¢ Pointer movement 

¢ Keyboard entry 

The drivers also manage a user entry list that your application can use for 
general storage purposes. 


The drivers associate each of the first three events with a specific region; 
they associate the keyboard entry event with the entire screen. 


When you define a region with a QIO, the driver uses the information you 
pass it to construct a list entry, which it places on the appropriate list. List 
entries typically contain the following information: 


¢ Region definition 


e Address of any AST routine defined to take action when the event 
occurs 


e Any AST parameter (token) 


When an event occurs, the driver searches the appropriate list; it uses the 
region definition to identify which list entry AST to issue. For example, 

if the driver detects a button transition, it searches the button transition 
list to determine whether the region where the transition occurred has a 
button transition AST enabled. For a keyboard entry, the first entry on the 
keyboard list is always invoked. 


The following sections summarize how drivers handle each type of event. 


1.3.5 Cursor Pattern List 


The cursor pattern list determines the pattern of the cursor for a region. 
Use the Define Pointer Cursor Pattern QIO to define the cursor shape and 


_ hot spot for a region. The list entry contains the following information: 


e Unique channel ID 


e Address of a 16 X 16 (16-word) bitmap that defines the shape of the 
cursor 


¢ Cursor hot spot, a point on the 16- by 16-pixel cursor that defines exact 
placement of the cursor image 


e¢ Cursor background style 


e §©Region definition 


See the Define Pointer Cursor Pattern QIO description for more details. 
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When the driver detects cursor movement, it searches the cursor pattern 
list for the appropriate ASTs to deliver. If a cursor pattern is to change, the 
bitmap image of the new pattern is located and loaded into the hardware. 
The new pattern is then superimposed on the appropriate area of the 
screen. 


V4.1—June 198 1-12.1 


Video Device Driver Introduction 


1.3.6 Pointer Button Transition List 


The driver uses this list to determine what action to take when a pointer 
button transition occurs. A button transition can be either up or down. It is 
detected by the hardware. 


A button transition event occurs when you press or release the pointer 
button within a region defined with the Enable Button Transition QIO. Each 
pointer button transition list entry contains the following information: 


e Unique channel ID 

¢ AST address 

¢ Region definition 

e Address of the longword to receive the input token indicating which 


pointer button is activated 


When a pointer button transition occurs, the driver searches the pointer 
button transition list for an entry describing the new region. The AST 
routine defined for that region determines what occurs when a pointer 
button is pressed. A token passes to the specified AST routine to signal 
the following: 


e Which button made a transition 

¢ Type of transition (up or down) 

The Enable Button Transition QIO description explains how button 
transitions are represented. 


If regions for pointer button transitions overlap, priority is given to the first 
rectangle on the list. 


1.3.7 Pointer Movement List 


The driver uses the pointer movement list to determine what action to take 
when the pointing device is moved. Use the Enable Pointer Movement 
QIO to define a region in which to take special action when pointer 
movement occurs. Each pointer motion list entry contains the following 
information: 


¢ Unique channel ID 

e AST address 

¢ Region definition 

e Address of the longword to receive the input token indicating the 
current physical position of the pointer 


As the driver searches the list, it compares the current pixel position of the 
pointer with the region definitions of all list entries. The current pointer 
location determines what event to trigger. If regions for pointer motion 
events overlap, priority is given to the first region on the list. 


If the pointer cursor moves outside a currently active region, a special exit 
token of -1 passes to the AST to notify it of the occurrence. When the 
cursor leaves the region, a process might want to perform some cleanup 
functions. 
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1.3.8 Keyboard Entry List 


1.3.9 Occlusion 
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The driver uses the keyboard entry list to determine the process to which 
it should deliver keyboard input. An application can use the Enable 
Keyboard Input QIO to request keyboard ownership. The driver then 
delivers input keystrokes to the process via AST routines you specify in the 
QIO. Keyboard list entries are not associated with regions. One keyboard 
is associated with each assigned channel. 


Each keyboard list entry contains the following information: 
¢ Unique channel ID 
¢ AST service routine address 


e Address of the longword that receives an input token when the AST 
routine is called 


See the Enable Keyboard Input QIO description for more details. 


This event differs from others, because when the first entry on the list 
is invoked, the list is not searched. The driver always inserts the active 
keyboard entry at the beginning of the list. 


| Popping or cycling operations cause a keyboard to become active. Cycling 


moves the current first entry on the list to the back of the list. Figure 1-5 
illustrates cycling. 


Figure 1-5 Cycling the Keyboard List 
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Keyboard C 
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Popping moves an entry from any position to the front of the list. 


In a windowing system, more than one window can address the same area 
of the screen. However, only one window can be displayed in one area at 
atime. Occlusion occurs when one window display hides some or all of 
another display. 
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Using Macros to Construct Compose Sequence Tables 

To construct a compose table, initialize it, then load the sequences you 
want to define. VMS Workstation Software provides macros to generate 
compose tables in SYS$LIBRARY:VWSSYSDEF.MLB: 


e VC$COMPOSE_KEYINIT—Initializes the table 
¢ VC$COMPOSE_KEY—Loads individual sequence definitions 
¢ VC$COMPOSE_KEYEND—Terminates the table 


These macros are also described in Appendix F. 


Initializing a Table 


Call VC$¢COMPOSE_KEYINIT to initialize a table. This macro has two 
parameters: 


¢ The address of the table, which it returns after it allocates space and 
initializes the table. Specify this parameter and use the returned 
address when you load the table. 


¢ The Compose_2 flag, which, if set equal to YES indicates that a 
two-stroke sequence table should be built. If the flag is not set, a 
three-stroke table is built. 


Loading a Compose Sequence 


Call VC$COMPOSE_KEY to load a compose sequence. This macro has 
four parameters that permit you to define the two input characters (either 
the two standard keys for a three-stroke sequence or the diacritical and 
standard key for a two-stroke sequence), the output string, and the output 
string length. Example 2-4 illustrates loading a three-stroke compose 
sequence. 


Example 2-4 Loading a Three-Stroke Compose Sequence 


-VCSCOMPOSE_KEY <‘%a/A/>,- } input A 
<‘a/"/>,;- 7; input " 
,- 3 Gefault output length 
<*xc4> : output character 


Terminating a Table 


Call VC$COMPOSE_KEYEND to terminate a keyboard table. This macro 
returns one parameter, the length of the table. Typically, you specify this 
parameter and use the returned length when you load the table. 
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2.4.5.2 


NOTE: 


Loading a Compose Table 

To load a compose table, use the Load Compose Sequence Table QIO 
with the address and size of the table and the channel of the keyboard 
entry with which you want to associate the table. The VC$COMPOSE_ 
KEYINIT and VC$COMPOSE_KEYEND macros return address and length, 
respectively. 


VMS Workstation Software is shipped with copies of the Digital standard 
three-stroke and two-stroke compose tables that reside in the driver. These 
tables are the default until you load alternates. 


Digital standard two-stroke compose sequerices are not supported on the 
North American keyboard. 


To revert to the default compose table, call the Revert to Default Compose 
Table QIO. 


Example 2-5 illustrates how to load a three-stroke compose table. 
(Appendix D shows this example in the context of a complete application 
program.) 


Example 2-5 How to Load a Three-Stroke Compose Table 


SET_COMPOSE3_TABLE: 


MOVL #<IOSC_QV_LOAD_COMPOSE_TABLE>, RO 

SQIOW_S CHAN = KBD_CHANI, - + change the compose table 
FUNC = #IO$_SETMODE, - 
Pl = (RO), - 
P4 = #COMPOSE3_TBL_LEN, - +; three-stroke table size 
P5 = #COMPOSE3_TBL ; three-stroke table addr 

BLBS RO,5S : not set on error 

BRW ERROR 

58: RSB 


VCSCOMPOSE_KEYINIT COMPOSE3_TBL }; generate an 

; empty table 

: £ill the table here 
tA 

VCSCOMPOSE_KEY <*%a/A/>,<‘a/"/>,,<“xc4> 

VCSCOMPOSE_KEY <*a/A/>,<‘a/'/>,,<*xcl> 

VCSCOMPOSE_KEY <*%a/A/>,<‘*a/*/>,,<*xc5> 

VCSCOMPOSE_KEY <‘a/A/>,<‘*a/A/>,<@> 

VCSCOMPOSE_KEY <‘a/A/>,<‘“a/E/>,,<*xc6> ; order sensitive 
VCSCOMPOSE_KEY <*a/A/>,<*a/*/>,,<*xc2> 

VCSCOMPOSE_KEY <*a/A/>,<‘a/_/>,,<*xaa> 


VCSCOMPOSE_KEYEND COMPOSE3_TBL_LEN : end the table 
3; and determine its 


; length 
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e Use the MACRO instruction INSQUE 


At specific intervals, the driver scans all request queues to check for work. 
If a queue contains DOPs, the driver removes the DOPs from the queue 
and performs the specified operations. The packets are stored on the 
queue in drawing operation order. 


Certain screen management circumstances require that request queue 
processing stop. Sometimes it is appropriate to stop a single viewport 
request queue; sometimes all viewport request queues must be stopped. 
The QIO interface contains a number of QIOs that manipulate the request 
queue. (A few DOPs also manipulate the request queue in a limited 
way.) Chapter 2 describes the circumstances under which an application 
manipulates the request queue. 


Return Queue 

A DOP is a data structure for which storage must be allocated. If you. 
process a large number of DOPs without any restrictions, they might 
consume all available system memory (or enough to degrade performance 
considerably). 


The QDSS driver provides the return queue for an application to reuse 
storage allocated for DOPs. The return queue, like the request queue, 

is a doubly linked list. Once a DOP is completely processed, the driver 
removes it from the request queue and inserts it on the return queue by 
simply updating the links. A DOP on the return queue is called a free DOP. 


To save space, an application can check the return queue for used DOP 
storage before it allocates memory for new drawing operations. 


Allocating DOPs 


To allocate storage for DOPs, use either the UISDC interface (see 
Chapter 5) or memory allocation system routines. When you allocate a 
DOP, initialize the DOP size fields of the DOP queue structure and the 
request queue structure (see Appendix B). You can choose either small or 
large size. 


Before it allocates new storage, an application should check the return 
queue for reusable DOP storage. (The UISDC interface does this.) An 
application can force the driver to wait for a DOP from the return queue by 
using the Get Free DOPs QIO. One of the parameters for this QIO allows 
an application to specify how many return queue DOPs to wait for before 
returning control to the application. The application can then reuse the 
storage by removing a DOP from the return queue. 


This feature can prevent allocation of too much system memory. For 
example, an application allocates 300 DOPs for processing on the request 
queue; before processing is complete, the application needs more DOPs 
for additional operations. If the application can allocate all the additional 
DOPs it requires, the application might consume all available system 
memory. However, when you specify a high number of DOPs to the 
Get Free DOPs, the application halts further memory allocation until that 
number of DOPs is available for reuse. 
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1.3.12 Deferred Queue 


NOTE: 


Return Queue Characteristics 


Because DOPs are allocated in two sizes, it is logical to regard the return 
queue as actually two queues, one where small DOPs are returned and 
another where large DOPs are returned. When you issue the Get Free 
DOPs QIO, you specify the number of DOPs to wait for as well as the 
specific return queue. 


Alternate Return Queue 


By default, a return queue is associated with each viewport through the 
DOP queue structure. However, you can use an alternate return queue 

to share return queues on a per-process or systemwide basis. To do this, 
specify the address of a return queue structure as the fourth parameter of 
the Get Viewport ID QIO when you create the viewport. (In this case, the 
return queue section of the viewport DOP queue structure is ignored.) See 
Appendix B for a description of this structure. 


When a portion of a viewport is occluded onscreen, one option is to write 
to an update region in offscreen memory. Sometimes, however, offscreen 
memory is so crowded that you cannot keep an update region there. In 
that case, you must save the writing operations on the deferred queue. 


The driver stores all operations directed to a portion of an unavailable 
viewport to the QDSS hardware on the deferred queue. Deferred queue 
operations can be executed whenever the previously occluded portion of 
the viewport becomes available. 


To prevent the deferred queue from consuming system resources, an 
application should update occluded viewports when the queue is full. 
The Notify Deferred Queue Full QIO informs an application the deferred 
queue is full. 


The Execute Deferred Queue QIO executes the operations on the deferred 
queue. Chapter 2 contains additional information on deferred queue 
operations. 
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2 An optional user-defined AST parameter delivered to the AST. 


3 Access mode at which to deliver the AST (maximized with the 
current access mode). 


4 The address of a longword where the driver stores the button 
transition value (token) when the AST service routine is called. 


Your application uses this longword to determine which pointer 
button has undergone a transition. The button transition value (the 
token) is a decimal value that indicates which button is activated; 
the transition values are 400, 401, 402, and 403. The system assigns 
these values to the pointer buttons sequentially starting with the 
select button, which is always 400. The driver stores the token 

_in the low-order word of the longword. Bit 15 of the high-order 
longword determines whether the transition is up or down: 1 
equals down and 0 equals up. 


The rest of the high-order word contains more control information 
that can be used to determine if the Shift, Control, or Lock keys 
are pressed. You can use these keys in combination as meta-keys as 
follows: 


e Bit 14 corresponds to the Shift key 
¢ Bit 13 corresponds to the Control key 
e Bit 12 corresponds to the Lock key 


e¢ The address of a pointer button characteristics block that determines 
whether delivery of subsequent transitions depends on all buttons 
being in the up position. By default, the specified button transition 
AST gets every transition until all buttons are returned to the up 
position. (See the description of this data structure in Appendix A.) 


e Address of a screen rectangle values block that describes the region 
associated with the button transition AST. 


By default, an entry is placed at the top of the list. However, you can 
determine the position of the entry in the list by specifying optional 
modifiers to the QIO. The modifiers can be used to perform the following 
functions: 


e Place the entry last on the list (QV_LAST) 
e Delete the entry (QV_DELETE) 
e Purge the type-ahead buffer (QV_PURG_TAH) 


If a button changes state (is clicked up or down), the driver checks the 
pointer position against the region descriptors of the button list entries. 
When the driver finds a region descriptor with the current pointer position, 
it fires the associated button transition AST. 


If two regions overlap, the first one on the list gets the AST. 
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Example 2-7 Typical Programming and Use of Pointer Button ASTs 





SET_BUTTONAST: 


SASSIGN_ 


BLBS 
BRW 
MOVL 
SQIOW_S 


1083: 


BLBS 

BRW 
20$: RSB 
BUT_BLOCK: 


- LONG 
- LONG 
- LONG 
» LONG 


BUT_REGION: 
- LONG 
- LONG 
- LONG 
-» LONG 


5 DEVNAM=WS_DEVNAM, - 


CHAN=BUT_CHAN 


RO,10$ 

ERROR 
#10SC_QV_ENABUTTON, RO 
CHAN=BUT_CHAN, - 
FUNC=#10$_SETMODE, - 
P1=(RO),- 
P2=#BUT_BLOCK, - 
P6=#BUT_REGION 

RO, 20$ 

ERROR 


BUT_AST 
0 

0 
BUTTON 


20 
20 
300 
300 


~e Ne Se Ne Ne Ne NO 


=e 


~e 


~e 


me se Se te Se we Se we Se Ne Ne Ne 


assign channel using 
logical name and 
channel number 

no error if set 
error 


enable button trans. 
channel 

QIO function code 
driver function code 
associated AST block 
associated region 

no error if set 


button transition AST 
specification block 
AST address 

AST parameter 

access mode 

button information 
longword 


associated region 
lower left corner 


upper right corner 


Example 2-7 illustrates the typical programming and use of pointer button 
ASTs. (Appendix D shows this example in the context of a complete 
applications program.) 





Using the Type-Ahead Buffer 


From keyboard input, pointer movement, and button transitions, the 
driver accepts three kinds of input: character input, pointer position, or 
button transition value. Often, input is received faster than an application 
processes it. When this happens, the character and button information is 
stored in the type-ahead buffer. (Pointer movement inputs the new pointer 
position, but if the input cannot be delivered, it is ignored, not buffered.) 


The type-ahead buffer is part of each entry on the list. It is 128 bytes long, 
so you can buffer 32 input tokens (each token is four bytes long). 


Getting Input from the Type-Ahead Buffer 


You can obtain input from the type-ahead buffer in two ways: 


¢ When you enable the entry, associate a repeating AST with it to process 
buffered input continuously. (For keyboards, you can also associate a 
repeating AST when you modify the keyboard.) 
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Programming to the Driver 


This chapter describes the following: 


¢ How to perform programming tasks when you write to the video device 
drivers 


¢ How to perform tasks common to both drivers or specific to either the 
OVSS or the ODSS driver 


¢ How to use specific QIOs and DOPs in combination to perform tasks 
Chapter 3 and Chapter 4 explain each function of the QIO interface in 


detail. Chapter 5 describes the QDSS system DOPs available for drawing 
to the display. 





Initializing the Screen 


N OTE: 


You must initialize the screen before you can write to it. Initialization 
places the VAXstation screen in a known state. Once initialization is 
complete, an application can issue QIOs and begin screen operations. 


You must initialize the screen before you perform a draw operation. If you 
fail to do this, the drawing operation will not work properly. 


To initialize the screen, use the Initialize QIO. This QIO has no parameters 
and is invoked only once for each application. 





Accessing the System Information Block 


The system information block (QVB or QDB, depending on your system) is 
a data structure that both drivers use to store information about the current 
state of video memory. This data structure consists of a number of fields; 
each is associated with a symbolic constant used to reference the field. See 
Appendices A and B for a full illustration and explanation of each field in 
these data structures. 


To obtain the address of the system information block, use the Get System 
Information QIO. This QIO returns a descriptor that contains the address 
and size of the block. To access any field in the block, use the returned 
address and the symbolic constants defined for that field. 


Using the QDB 


If a QDSS application is using only the UISDC DOP interface, it does not 
have to access the QDB. However, under some circumstances (for example, 
if it manipulates the pointer position or requires tablet information), it 
might need the system information stored in the QDB. Example 2-12, 
later in this chapter, shows how an application uses the QDB to get the 
systemwide viewport ID. 
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Using the QVB 


Typically, before a QVSS application can perform a drawing operation, it 
must obtain specific video memory information from the QVB: 


¢ Starting address of video memory to set bits (draw) in memory 


e Address of the scanline map to map to the screen any lines in memory 
it wants to display 


Section 2.10 describes how to use the QVB for drawing operations. The 
following code segment shows a call that obtains the descriptor for the 
QVB. 


! Declare QDB descriptor and buffer 
INTEGER*4 QDB_DESC(2) 


{ Obtain a channel for the call 

CALL SYSSASSIGN (’SYSSWORKSTATION’, ! device name 

2 CHAN, , ) ! channel 

! Get the QVB 

CODE = I0$_SENSEMODE 

STATUS = SYSSQIOW (, 

2 %VAL (CHAN), ! channel 
1] 


2 %VAL({(CODE), QIO function code 
2 ere 

2 %VAL(IO$C_QV_GETSYS), 

2 QVB_DESC,,,,) ! address of descri 
IF (STATUS .NE. 1) THEN 


CALL LIBSSIGNAL (%*VAL (STATUS) ) 
END IF 
{ Extract from the QVB 
CALL EXTRACT_OQVB (%VAL(QVB_DESC(2)), ! 
2 VIDEO_ADDR, ! 
2 SCANLINE_ADDR) ! 


pass address by value 
video memory buffer 
scanline map buffer 


KEKE KKKKEKEKEKKKKKEKKKKRKEK KKK 


t 
! * EXTRACT _QVB SUBROUTINE * 
' 


KEKKEKKKEKEREKKKKEKKKKKKRKRKKKEK 


FUNCTION EXTRACT_QVB (QVB, VIDEO, SCAN) 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ’VWSSYSDEF’ 


! Associate the predefined structure w/ QVB 
RECORD /QVB_COMMON_STRUCTURE/ QVB 


VIDEO = QVB.QVBSL_MAIN_VIDEOADDR 
SCAN = QVB.QVBSL_MAIN_MAPADDR 


RETURN 
END 


Programming to the Driver 





2.3 Using Channels with Video Device Drivers 


The drivers use channel numbers to identify application list entries. The 
drivers track various events by listing event entries (see Section 1.3.4). 
When an application uses the QIO interface to place an entry on a list, it 
associates the entry with a channel number (using the chan parameter of 
the QIO). To obtain a unique channel number, use the $ASSIGN system 
service. (See VAX/VMS System Services Reference Manual.) 


For each application list entry, the channel number must be unique to that 
list. That is, if a process uses channel 1 to create an entry on the keyboard 
list, it cannot use channel 1 to create another entry on the keyboard list. 

It must obtain another channel to create another entry. When it adds or 
deletes entries, the driver uses the channel number to identify each entry 
uniquely. 


However, the same channel number can be used across lists. For example, 
an application can use channel 1 to create an entry on the button transition 
list, the keyboard entry list, and the cursor pattern list. 





2.4 Using the Keyboard 


Driver keyboard functions enable an application to perform the following 
operations: 


e¢ Receive keyboard input 
e Modify keyboard characteristics 
¢ Modify keyboard character sets 


¢ Compose characters that do not exist as standard keys 


The following sections describe these capabilities. 


2.4.1 Receiving Keyboard Input 


To receive input from a keyboard, an application must explicitly enable the 
keyboard for input with the Enable Keyboard Input QIO. This creates an 
entry on the keyboard entry list. When you enable a keyboard, you can 
specify: 


e¢ The address of a four-longword AST specification block. The four 
longwords contain the following information: 


1 The address of an AST routine that determines what action to take 
when input is received. This is called a keystroke AST because it is 
fired for each keystroke entered. 


If no AST routine is specified, input is stored in the type-ahead 
buffer and delivered either when an AST region is declared with 
the same channel or when a Get Next Input Token QIO is issued. 


2 An optional user-defined AST parameter that is delivered to the 
AST. 


3 Access mode at which to deliver the AST (maximized with the 
current access mode). 
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4 A zero. 


e The address of an AST routine invoked whenever the entry is made 
active (brought to the top of the list). This is called a request AST (or 
control AST). It is fired only once for each entry activation. Only one 
keyboard can be active at a time. Typically, the request AST performs 
any necessary actions that the enabled keyboard requires; for example, 
it pops an obscured window to make displayed input visible. 


e The address of a keyboard characteristics block that describes the 
characteristics of the keyboard. Each keyboard is associated with a 
set of characteristics (key click, auto repeat, and so on) defined in this 
data structure. You can choose the default characteristics or modify the 
defaults. Section 2.4.2 discusses keyboard characteristics in detail. 


By default, an entry is placed at the top of the list when a keyboard is 
enabled. However, an application can determine the position of the entry 
in the list by specifying optional modifiers to the QIO. The application can 
use the modifiers to perform the following operations: 


e Cycle the list, which moves the top entry to the end of the list (QV_ 
CYCLE) 


¢ Place the entry last on the list (QV_LAST) 
¢ Delete the entry (QV_DELETE) 
e Purge the type-ahead buffer (QV_PURG_TAH) 


Typically, an application defines one keyboard for each window. However, 
it can define the characteristics of each keyboard differently from window 
to window. This feature permits you to create ‘‘virtual’’ keyboards. 
Although there is only one physical keyboard, you can define a number 
of different keyboards, and an application can enable any number of 
keyboards as long as it keeps track of them. When you no longer need a 
keyboard, delete it as follows: 


e Use the QV_DELETE modifier with the QIO, or 


e Deassign the associated channel 


Example 2-1 illustrates: 
¢ A typical assignment of two terminal channels 
¢ Keyboard requests on those channels 


e Associated AST routines 


(Appendix D shows this example in the context of a complete application 
program.) 
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Example 2-1 Enabling Keyboard Requests 





P2_BLOCK2: 


e 
rf 
. 
, 
° 
a 
e 
Lf 
e 
LA 


~e se Ne Ne Ne we 


se Ne we Ne Ne Se Se Ne 


~e se Ne Ne Ne 


AST specification block 2 

AST address 

AST parameter 

AST delivery mode 

input token 

;AST parameter message 


control AST specification 
block - for both ASTs 
control AST address 

AST parameter 

AST delivery mode 

must be zero 


assign channel using 
logical name and 
channel number 

no error if set 
error 


enable keyboard AST 
request to RO 
assigned channel 

set mode QIO 
keyboard AST request 
user AST routine 
control AST routine 
no error if set 


send acknowledgment 
message 


was F5 typed? 


cycle the keyboard list 
and exit 


send character typed 


was a "C" typed? 


cycle the keyboard list 


was an "F" typed? 


.» LONG KBD_AST 
- LONG ACK2 
» LONG 0 
.» LONG CHARACTER 
ACK2: -ASCID /INPUT ACKNOWLEDGED CHANNEL 2/ 
P3_ BLOCK: 
.» LONG CTL_AST 
-» LONG 0 
«LONG 0) 
- LONG 0 
SET_KBDAST: 
SASSIGN_S DEVNAM=WS_DEVNAM, - 
CHAN=KBD_CHAN2 
BLBS RO,208 
BRW ERROR 
2083 MOVL #IO$C_QV_ENAKB, RO 
SQIOW_S CHAN=KBD_CHAN2,- 
FUNC=#1I0S_SETMODE, - 
P1=(RO),- 
P2=#P2_BLOCK2,- 
P3=#P3_BLOCK 
BLBS RO,30S 
BRW ERROR 
KBD_AST: 
F5_AST: 
«WORD 
PUSHL 4(AP) 
CALLS #1,G°LIBSPUT_LINE 
BLBS RO, 108 
53: BRW ERROR 
108: CMPW #KEYSC_F5,CHARACTER 
BNEQ 208 
BSBW CYCLE_KBD 
BRB 40S 
2083 PUSHAL DESC 
CALLS #1,G*LIBSPUT_LINE 
BLBC RO,5$ 
CMPB #°A/C/, CHARACTER 
BNEQ 30$ 
BSBW CYCLE_KBD 
BRB 40$ 
3083 CMPB #°A/F/, CHARACTER 
BNEQ 40s 


SSETEF_S EFN=#2 


yes, exit program 





Example 2-1 Cont’d. on next page 
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Example 2-1 (Cont.) Enabling Keyboard Requests 


408: 


CTL_AST: 


593: 
1083: 


RET 


«WORD 
PUSHAL 
CALLS 
BLBS 
BRW 


RET 


; send acknowledgment 


#1,G°LIBSPUT_LINE } message 
RO, 108 


Keyboard Characteristics 


Keyboards have a set of default characteristics associated with them. These 
default characteristics are defined by a data structure called the system 
characteristics block. Appendix A illustrates this data structure and lists the 
default keyboard characteristics. 


Modify the default characteristics by specifying a system characteristics 
block as the fourth parameter of the Modify Systemwide Characteristics 
QIO. This block consists of four longwords with the following parameters: 


e¢ Longword 1—Bit mask of the characteristics to enable 
¢ Longword 2—Bit mask of the characteristics to disable 
¢ Longword 3—Key-click volume value in the range 1 to 8 (1 is loudest). 


¢ Longword 4—Screen saver time, in minutes 


To enable or disable default values, specify the predefined QVBDEF 
constant associated with each characteristic (also listed in Appendix A) 
in the proper longword. If you enable the key-click or screen saver 
characteristics, their values in the third and fourth longword are used. 


Once you modify the systemwide defaults, if you enable a keyboard 
without specifying characteristics, the keyboard assumes the new default 
values. 


To define the keyboard characteristics (auto repeat, key-click sound, 
function key transition) for a particular keyboard entry, specify the address 
of a keyboard characteristics block as the fourth parameter of the Enable 
Keyboard Input QIO. This block also consists of four longwords with the 
following parameters: 


e Longword 1—Bit mask of the characteristics to enable 
e Longword 2—Bit mask of the characteristics to disable 


e Longword 3—Key-click volume value in the range 1 to 8 (1 is loudest). 


Note that Longword 4 must be zero. 


- Programming to the Driver 


You can enable the same characteristics for a specific keyboard as for 
the systemwide defaults, except for the screen saver time, which is a 
systemwide characteristic (there is only one screen). See Appendix A. 


For example, assume an application enables two keyboards, one with 
autorepeat and the other without autorepeat. When one keyboard is active, 
holding down any key causes it to be entered repeatedly; when the other 
keyboard is active, the key is entered only once. 


To modify the characteristics of an existing keyboard, specify a keyboard 
characteristics block as the fourth parameter of the Modify Keyboard 
Characteristics QIO. Note that you can also use this QIO to change the 
keystroke AST and request AST associated with a keyboard. 


2.4.3 Modifying the Keyboard Table 


2.4.3.1 


The keys on the main keypad array of the physical keyboard are 
programmable. That is, an application can associate the keys of the 
keyboard with any of the 255 characters in the multinational character 
set (including diacritical characters). (Appendix I shows the multinational 
character set.) An application can define several character sets to be 
accessed at different times by the same physical keyboard. 


To define a character set, construct a data structure (keyboard table), then 
use the Load Keyboard Table QIO to load the new table. 


Constructing a Keyboard Table with Macros 

To construct a keyboard table, initialize it with the default table values, then 
override any values you want to modify. SYS$LIBRARY:$QVBDEF.MLB 
contains the following macros to generate keyboard tables: 


¢ VC$KEYINIT—Initializes the table 
¢ VCS$KEY—Loads individual key definitions 
¢ VC$KEYEND—Terminates the table 


These macros are described in Appendix E. 


Initializing a Table 


Call VC$KEYINIT to initialize a table. This macro has one parameter, the 
address of the table, which it returns after allocating space and initializing 

the table. Specify this parameter and use the returned address when you 

load the table. By default, the system loads the North American keyboard 
table. 


Loading Key Definitions 


Call VC$KEY to load new key definitions. Several parameters permit you 
to define the various states of a given key. Note that you modify only 
the keys that are different from the default keys. Loading key definitions 
overrides the default definitions loaded by VC$KEYINIT. 


Depending on how you press the Shift, Control, and Lock keys in 
combination with it, a keyboard key can have eight different states. For 
each key, the keyboard table associates each state with a one-byte ASCII 
value that represents a character from the multinational character set. Each 
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key is described by a quadword in the table. Table 2-1 lists the key states 
and the byte within the quadword that describes each state. 


Table 2-1 Key States 


Byte State 
Value of key 





Value of key if Shift key is also pressed 

Value of key if Control key is also pressed 

Value of key if both Shift and Control keys are also pressed 
Value of key if Lock is also pressed 

Value of key if both Lock and Shift keys are also pressed 
Value of key if both Lock and Control keys are also pressed 


ON OO FF WN + 


Value of key if Lock, Shift, and Control keys are also pressed 





When you use VC$KEY to load a key, you specify the following 
information: 


e Nine parameters 
e Ordinal key position 


e ASCII value associated with each of the eight states 


Figure 2-1 shows the order of keys in the keyboard table. It illustrates the 
relationship of the physical key on the keyboard to the ordinal key position 
in the keyboard table (numerals in small print). This table corresponds to 
the North American keyboard character layout. 


Figure 2-1 Keyboard Table Layout 


2's ‘Is ‘Is ‘te ‘I> ‘ls “Ie “lo fof | 
2 4 5 6 7 8 - = 
Tab Q |w |e T |Ily ju jt fo fp fe Wy 

14 15 “| 3 9 29 2 2 2ait[ asi] ] 2s 
Ctrl Lock A Ss D F G J K L : " | 
; 26 23 id 29 30 32 32 atte sip, 38 \ 
Shih > iz |x le |v je iN iM |] 1? I[sre 

< 38 39 40 a 42 43 43 oa 36 | : 47 / 43 













Compose 
Character 
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The following example shows the loading of the tenth key of the keyboard 
table: 


<“x0FF>,- 
<4xOFF> 


Lock/Control/key = undefined 
Lock/Shift/Control/key = undefined 


VCSKEY 10,- 3; ordinal key position 

<*a/9/>,- ; key = 9 
<a/)/>,- 3 Shift/key = ) 
<“x0OFF>,- 3; Control/key = undefined 
<Ax0FF>,- 3; Shift/Control/key = undefined 
<*a/9/>,- 3; Lock/key = 9 
<*a/)/>,- 3 Lock/Shift/key = ) 

? 

, 


Note that the hexadecimal value OFF denotes an undefined key (no 
character is delivered). 


Table 2-2 shows the decimal values that represent diacritical characters. 
(Section 2.4.5 contains additional information on diacritical characters.) 


Table 2-2 Diacritical Characters 


Diacritical Mark Equivalent Character Decimal Value 
Diaeresis (umlaut) A 128 

Acute accent : 129 

Grave accent ; 130 

Circumflex accent 131 

Tilde 7 132 

Ring 2 133 

(Reserved) 134-159 





Terminating a Table 


Call VC$KEYEND to terminate a keyboard table. This macro returns one 
parameter, the length of the table. Specify this parameter and use the 
returned length when you load the table. 


Example 2-2 shows how you can modify the North American keyboard 
layout. (Appendix D shows this example in the context of a complete 
application program.) 


Constructing a Keyboard Table Without Macros 

It is possible to construct a keyboard table without using the provided 
macros. Such a keyboard table must conform to the structure illustrated in 
Figure 2-2. 
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VCSKEYINIT KB_LAYOUT_TBL ; generate the new table 
; modify only the characters 
; specified 


VCSKEY 10,<‘*a/9/>,<‘*a//>) ,<*xOFF>,<*xOFF>,- 
<4a/9/>,<*a//>) ,<*xOFF>,<*xOFF> 

VCSKEY 11,<‘a/0/>,<*a/=/>,<*xOFF>,<*x0OFF>,- 
<“a/0/>,<“a/=/>,<*xOFF>, <*x0OFF> 

VC$KEY 12,<*x081>,<‘%a/?/>,<*xOFF>,<*xOFF>,- ;diacritical (’) 
<4x081>,<a/?/>,<*xOFF>,<“xOFF> 

VCSKEY 13,<*x082>,<*x083>,<°xX0O1E>,<“xO1E>,- ;diacriticals (* %) 
<*X082>,<*x083>,<*x0FF>,<*x0OFF> 

VCSKEY 19,<‘*a/z/>,<*a/Z/>,<*x01A>,<*x01A>,- 
<Aa/z/>,<*a/Z/>,<*xO1A>,<*xO1A> 

VCSKEY 24,<*xOE8>,<*xOFC>,<*x0FF>,<*x0OFF>,- 
<“xOE8>,<*XOFC>,<*x0OFF>,<*x0OFF> 

VCSKEY 25,<*x080>,<*x084>,<*xKOFF>,<“xOFF>,- ;diacriticals (" ~) 
<*x080>,<*x084>,<*xOFF>,<*xOFF> 


VCSKEYEND KB_LAYOUT_TBL_LEN ; end the table, 
; and determine its length 





Figure 2-2 Keyboard Table Description 
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version number 





Sicimvendiapiaeinnaninicsmeseiseeutcseoient 


ZK 5347-86 





e The first quadword of the table must contain the table version number. 
Typically this value is 1. 


e Each subsequent quadword describes the eight states of a key in the 
main array of the keyboard, in the order shown in Figure 2-1. 


¢ Every key must be defined. 


2.4.3.3 


NOTE: 
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Loading a Keyboard Table 

To load a keyboard table, use the Load Keyboard Table QIO, specifying 
the address and size of the table and the channel of the keyboard entry 
with which you associate the table. Note that the VC$KEYINIT and 
VC$KEYEND macros return address and length, respectively. 


When a keyboard table is loaded and the associated keyboard becomes 
active, the physical keyboard reflects the table definitions. 


You can revert to the default keyboard table by calling the Revert to Default 
Keyboard Table QIO. 


If a private table was loaded, this QIO also returns the space used to pool. 


Example 2-3 is a typical routine for loading a keyboard table. (Appendix D 
shows this example in the context of a complete application program.) 


Example 2-3 Loading a Keyboard Table 


SET_FRENCH_KB: 


MOVL #<IO$C_QV_LOAD_KEY_TABLE>, RO 


SQIOW_S CHAN 
FUNC 
Pl = 
P2 = 
P3 = 
BLBS RO,5$ 


BRW ERROR 
5$3 RSB 


= KBD_CHANI, - ; change the keyboard 
= #IO$_SETMODE, - ; layout 
(RO), - 
#KB_LAYOUT_TBL_LEN, - ; keyboard table size 
#KB_LAYOUT_TBL ; keyboard table 

; address 

’ 


* no error if set 


Composing Nonstandard Characters 


Compose Sequences 


Use compose sequences to define combinations of keys to represent 
multinational characters not already defined as standard keys in the 
keyboard table. 


Depending on your keyboard, you can use two types of compose 
sequences: 


e Three-stroke sequences—Press the Compose key, then press two 
standard keys. All keyboards support three-stroke sequences. 


¢ Two-stroke sequences—Press a diacritical mark, then press a standard 
key. The North American keyboard does not support two-stroke 
sequences. 
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Diacritical Marks 
A diacritical mark is one of the following nonspacing characters: 


Grave accent—E 
Acute accent—E 
Circumflex accent—E 
Tilde—N 
Diaeresis (umlaut)—E 
Ring—A 


Diacritical marks are available on all but the North American keyboard. 
(This is why you cannot perform two-stroke sequences on the North 
American keyboard.) Diacritical marks vary among the keyboards 
according to the relative usage of characters with diacritical marks. Note 
that only one of several characters shown on a key cap can be a diacritical 
mark; some keyboards have keys with both a standard character and a 
diacritical mark. 


To define compose sequences, construct a compose sequence table data 
structure (either two-stroke, three-stroke, or both), then load the table with 
the Load Compose Sequence Table QIO. 


2.4.5 Constructing Compose Sequence Tables 


A compose sequence table lists a series of compose sequences. The 
structures of three-stroke and two-stroke tables differ slightly. 


Three-Stroke Compose Sequence Table Structure 
Three-stroke compose tables have three parts: 


1 A longword with the version number for the table (typically this value 
is 1). 


2 A series of longwords that list the two standard keys used in the 
compose sequence and hold an address that points to the associated 
output string, in the format shown in Figure 2-3. 


Figure 2-3 Three-Stroke Compose Sequence Table Description 


3+2 1 0 By 


address of output string char 2 char 1 
(output) (input) (input) 


ZK-445 1-85 


3 Counted string that bytes 2 and 3 of the longword (address of output 
string) point to. All counted strings must be grouped together and mus 
follow the list of longwords that describe the compose sequences. 


Figure 2-4 shows the structure of an entire three-stroke compose sequence 
table. 
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Figure 2-4 Three-Stroke Compose Sequence Table 


version numb 


address of output string char 2 char 1 
(output) (input) (input) 


(list of longword descriptions) 
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Two-Stroke Compose Sequence Table Structure 


Two-stroke compose sequence tables have four parts: 


1 
2 


A longword with the table version number (typically this value is 1). 


A 32-byte diacritical table that defines which characters are diacriticals. 


Each bit in the diacritical table corresponds to the equivalent ASCII 
character code in the multinational character set. If a bit is set in this 
table, the corresponding character is considered a diacritical character. 
Thus, you can define nonstandard diacritical characters. For example, 
if you set bit 65 (decimal), the uppercase letter ‘’A’”’ is a diacritical 
character. If you set bit 112 (decimal), the lowercase letter ‘‘p’’ is a 
diacritical character. 


To support standard diacritical characters, represent the characters with 
the decimal values shown in Table 2-3. 


Table 2-3 Diacritical Characters 


Diacritical Mark Equivalent Character Decimal Value 
Diaeresis (umlaut) A | 128 

Acute accent ; 129 

Grave accent : 130 

Circumflex accent ° 131 

Tilde ~ 132 

Ring bs 133 

(Reserved) 134-159 


3 


A series of longwords that list the diacritical key and the standard key 
used in the compose sequence and hold an address that points to the 
associated output string, in the format shown in Figure 2-5. 
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Figure 2-5 Two-Stroke Compose Sequence Table Description 


342 1 0 
address of output string char 2 char 1 | 
(output) (input) (input) 
2K-445 1-85 


Place the list of longwords in the table in ascending order by ASCII 


Byt 


collating sequence with both input characters, as shown in the following 


example. 

Incorrect Table Correct Table 
ss18 AE1F 
AE1L A~1A 

“aia “aia 

A-1A ss1B 


4 The series of counted strings that bytes 2 and 3 of each longword 
(address of output string) point to. All the counted strings must be 


grouped together and must follow the list of longwords that describe 
the compose sequences. 


Figure 2-6 shows the structure of an entire two-stroke compose sequence 
table. 


Figure 2-6 Two-Stroke Compose Sequence Table 


31 


version number 


diacritical table 
(32 bytes) 


address of output string char 2 char 1 
(output) (input) (input) 


(list of longword descriptions) 
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Using Macros to Construct Compose Sequence Tables 

To construct a compose table, initialize it, then load the sequences you 
want to define. VMS Workstation Software provides macros to generate 
compose tables in SYS$LIBRARY:$VWSSYSDEF.MLB: 


*¢ VC$COMPOSE_KEYINIT—Initializes the table 
¢ VC$COMPOSE_KEY—Loads individual sequence definitions 
¢ VC$COMPOSE_KEYEND—Terminates the table 


These macros are also described in Appendix F. 


initializing a Table 


Call VC$COMPOSE_KEYINIT to initialize a table. This macro has two 
parameters: 


e The address of the table, which it returns after it allocates space and 
initializes the table. Specify this parameter and use the returned 
address when you load the table. 


¢ The Compose_2 flag, which, if set equal to YES indicates that a 
two-stroke sequence table should be built. If the flag is not set, a 
three-stroke table is built. 


Loading a Compose Sequence 


Call VC$COMPOSE_KEY to load a compose sequence. This macro has 
four parameters that permit you to define the two input characters (either 
the two standard keys for a three-stroke sequence or the diacritical and 
standard key for a two-stroke sequence), the output string, and the output 
string length. Example 2-4 illustrates loading a three-stroke compose 
sequence. 


Example 2-4 Loading a Three-Stroke Compose Sequence 


VCSCOMPOSE_KEY <‘’a/A/>,- ; input A 
<Aa/"/>,- 3; input " 
a 


v 


; default output length 


<“xc4> ; output character 


Terminating a Table 


Call VC$COMPOSE_KEYEND to terminate a keyboard table. This macro 
returns one parameter, the length of the table. Typically, you specify this 
parameter and use the returned length when you load the table. 
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2.4.5.2 


NOTE: 


Loading a Compose Table 

To load a compose table, use the Load Compose Sequence Table QIO 
with the address and size of the table and the channel of the keyboard 
entry with which you want to associate the table. The VC$COMPOSE_ 
KEYINIT and VC$COMPOSE_KEYEND macros return address and length, 
respectively. 


The VMS Workstation is shipped with copies of the Digital standard three- 
stroke and two-stroke compose tables that reside in the driver. These 
tables are the default until you load alternates. 


Digital standard two-stroke compose sequences are not supported on the 
North American keyboard. 


To revert to the default compose table, call the Revert to Default Compose 
Table QIO. 


Example 2-5 illustrates how to load a three-stroke compose table. 
(Appendix D shows this example in the context of a complete application 
program.) 


Example 2-5 How to Load a Three-Stroke Compose Table 





SET_COMPOSE3_ TABLE: 
MOVL #<IO$C_QV_LOAD_COMPOSE_TABLE>, RO 


SQIOW_S CHAN = KBD_CHANI, - : change the compose table 
FUNC = #I10$_SETMODE, — 
Pl = (RO), - 
P4 = #COMPOSE3_TBL_LEN, -. ; three-stroke table size 
P5 = #COMPOSE3_TBL ; three-stroke table addr 

BLBS RO,5S8 ; not set on error 

BRW ERROR 

S5s3 RSB 


VCSCOMPOSE_KEYINIT COMPOSE3 TBL ; generate an 

; empty table 

; fill the table here 
i 

VCSCOMPOSE_KEY <“a/A/>,<“a/"/>,,<*xc4> 

VCS$COMPOSE_KEY <‘a/A/>,<‘a/'/>,,<*xcl> 

VCSCOMPOSE_KEY <‘a/A/>,<‘*a/*/>,,<*xc5> 

VCSCOMPOSE_KEY <*a/A/>,<*a/A/>,<@> 

VCSCOMPOSE_KEY <‘’a/A/>,<“a/E/>,,<*xc6> ; order sensitive 
VCSCOMPOSE_KEY <‘a/A/>,<‘a/*/>,,<*xc2> 

VCSCOMPOSE_KEY <“a/A/>,<*a/_/>,,<*xaa> 


s end the table 
3 and determine its 
: length 


VCSCOMPOSE_KEYEND COMPOSE3_TBL_LEN 
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Using a Pointer Device 


The drivers detect two pointer-related conditions: 
¢ Pointer movement 


e Pointer button transition 


The QIO interface enables you to associate regions of the screen with action 
ASTs the driver fires whenever it detects pointer movement or a pointer 
button transition (clicking up or down). The action ASTs are application- 
dependent and enable you to perform such screen manipulation as 
highlighting a menu when the pointer moves into it or performing an 
action once you select a menu item. . 


The driver uses separate lists to track pointer movement and button 
transitions. The following sections describe how to create list entries 
for pointer movement and button transitions. 


Creating a Pointer Movement Entry 


Use the Enable Pointer Movement QIO to create a pointer movement 
entry. When you create a pointer movement entry, specify the following 
information: 


e The address of a four-longword AST specification block. The four 
longwords contain the following parameters: 


1 The address of an AST routine that determines what action to take 
when movement is detected within the specified region. 


An optional user-defined AST parameter delivered to the AST. 


Access mode at which to deliver the AST (maximized with the 
current access mode). 


4 The address of a longword where the driver stores the new cursor 
position so it is accessible to the application. 


The low-order word of the longword holds the the X pixel position 
and ranges from 0 to 1023, where 0 is the left side of the screen. 
The high-order word holds the the Y pixel position and ranges from 
0 to 863, where 0 is the bottom of the screen. 


e The address of an AST routine invoked whenever the pointer exits the 
specified region. Typically, this AST performs any necessary cleanup 
actions. For example, it turns off a region highlighted by the action 
AST. 


e The address of a screen rectangle values block that describes the region 
to be associated with the ASTs. | 


By default, an entry is placed at the top of the list. However, an application 
can determine the position of the entry in the list by specifying optional 
modifiers to the QIO. The modifiers can be used to perform the following 
functions: 


e Place the entry last on the list (QV_LAST) 
e Delete the entry (QV_DELETE) 
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Whenever you move the pointer (mouse, stylus, or puck), the driver 
checks the pointer position against the region descriptors of the pointer 
movement list entries. When the driver finds an entry whose region 
descriptor includes the current pointer position, the driver fires the action 
AST associated with that entry. 


If you specify an exit AST, the driver fires that AST when it discovers that 
the pointer position is no longer within the specified region. 


If two regions overlap, the first one on the list gets the AST. 


Example 2-6 illustrates how to program a pointer motion AST. 
(Appendix D shows this example in the context of a complete applications 
program.) 


Example 2-6 How to Program a Pointer Motion AST 


10$: MOVL #10$C_QV_MOUSEMOV, RO 
$QIOW_S CHAN=MOUSE_CHAN, - 
FUNC=#10$_SETMODE, - 
P1=(RO),- 
P2=#MOUSE_BLOCK, - 


enable pointer motion 
channel 

QIO function code 
driver function code 
associated AST block 


we Ne Ne Ne Me 


P6=#MOUSE_REGION : associated region 
BLBS RO,20$8 ¢s no error if set 
BRW ERROR 
208: RSB 


MOUSE_BLOCK: pointer region AST 
specification block 

AST address 

AST parameter 

access mode 

new pointer cursor position 
; storage 


-LONG MOUSE_AST 
LONG MOUSE_ACK 
-LONG 0 

LONG MOUSE_XY 


~e Ne Ne Ne Ne Ne te 


se 


MOUSE_REGION: pointer region 


.» LONG 400 * lower left corner 
- LONG 400 
- LONG 800 + upper right corner 


* LONG 800 


Creating a Pointer Button Transition Entry 


Use the Enable Button Transition QIO to create a pointer button 
transition. When you create a button transition entry, specify the following 
information: 


e The address of a four-longword AST specification block. The four 
longwords contain the following parameters: 


1 The address of an AST routine that determines what action to take 
when a transition is detected within the specified region. 


If no AST routine is specified, input (the button transition) is store: 
in the type-ahead buffer and delivered either when you declare an 
AST region with the same channel or when you issue a Get Next 
Input Token QIO with the same channel. 
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2 An optional user-defined AST parameter delivered to the AST. 


3 Access mode at which to deliver the AST (maximized with the 
current access mode). 


4 The address of a longword where the driver stores the button 
transition value (token) when the AST service routine is called. 


Your application uses this longword to determine which pointer 
button has undergone a transition. The button transition value (the 
token) is a decimal value that indicates which button is activated; 
the transition values are 400, 401, 402, and 403. The system assigns 
these values to the pointer buttons sequentially starting with the 
select button, which is always 400. The driver stores the token 

in the low-order word of the longword. Bit 15 of the high-order 
longword determines whether the transition is up or down: 1 
equals down and 0 equals up. 


The rest of the high-order word contains more control information 
that can be used to determine if the Shift, Control, or Lock keys 
are pressed. You can use these keys in combination as meta-keys as 
follows: 


e Bit 14 corresponds to the Shift key 
e Bit 13 corresponds to the Control key 
¢ Bit 12 corresponds to the Lock key 


e The address of a pointer button characteristics block that determines 
whether delivery of subsequent transitions depends on all buttons 
being in the up position. By default, the specified button transition 
AST gets every transition until all buttons are returned to the up 
position. (See the description of this data structure in Appendix A.) 


e Address of a screen rectangle values block that describes the region 
associated with the button transition AST. 


By default, an entry is placed at the top of the list. However, you can 
determine the position of the entry in the list by specifying optional 
modifiers to the QIO. The modifiers can be used to perform the following | 
functions: 


e Place the entry last on the list (QV_LAST) 
e Delete the entry (QV_DELETE) . 
e Purge the type-ahead buffer (QV_PURG_TAH) 


If a button changes state (is clicked up or down), the driver checks the 
pointer position against the region descriptors of the button list entries. 
When the driver finds a region descriptor with the current pointer position, 
it fires the associated button transition AST. 


If two regions overlap, the first one on the list gets the AST. 


Example 2-7 illustrates the typical programming and use of pointer button 
ASTs. (Appendix D shows this example in the context of a complete 
applications program.) 
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Example 2-7 Typical Programming and Use of Pointer Button ASTs 





SET_BUTTONAST: 


10$: 


20S: 


SASSIGN_ 


BLBS 
BRW 
MOVL 
$QIOW_S 


BLBS 
BRW 
RSB 


BUT_BLOCK: 


- LONG 
» LONG 
- LONG 
- LONG 


BUT_REGION: 


- LONG 
- LONG 
- LONG 
« LONG 


5 DEVNAM=WS_DEVNAM, -— 


CHAN=BUT_CHAN 


RO, 10$ 

ERROR 
#10$C_QV_ENABUTTON, RO 
CHAN=BUT_CHAN, - 
FUNC=#10$_SETMODE,- 
P1=(RO),- 
P2=#BUT_BLOCK, - 
P6=#BUT_REGION 

RO,20S 

ERROR 


BUT_AST 
0 

0 
BUTTON 


20 
20 
300 
300 


se se Se we Ne Ne Ne 


ue 


“ee 


we 


~e ~e Ne se se Ne Ne Ne we Ne NO we 


assign channel using 
logical name and 
channel .number 

no error if set 

error 


enable button trans. 
channel 

QIO function code 
driver function code 
associated AST block 
associated region 

no error if set 


button transition AST 
specification block 
AST address 

AST parameter 

access mode 

button information 
longword 


associated region 
lower left corner 


upper right corner 





Using the Type-Ahead Buffer 


From keyboard input, pointer movement, and button transitions, the 
driver accepts three kinds of input: character input, pointer position, or 
button transition value. Often, input is received faster than an application 
processes it. When this happens, the character and button information is 
stored in the type-ahead buffer. (Pointer movement inputs the new pointer 
position, but if the input cannot be delivered, it is ignored, not buffered.) 


The type-ahead buffer is part of each entry on the list. It is 128 bytes long, 
so you can buffer 32 input tokens (each token is four bytes long). 





Getting Input from the Type-ahead Buffer 


You can obtain input from the type-ahead buffer in two ways: 
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When you enable the entry, associate a repeating AST with it to process 
buffered input continuously. (For keyboards, you can also associate a 
repeating AST when you modify the keyboard.) 


Issue a Get Next Input Token QIO to process a single input token frorr 
the buffer (this QIO can have an AST associated with it—in either case 
the input is delivered in the IOSB block). This type of single-token 

processing is called a ‘‘one shot.”’ 
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e Issue a Get Next Input Token QIO to process a single input token from 
the buffer (this OQIO can have an AST associated with it—in either case, 
the input is delivered in the IOSB). This type of single-token processing 
is called a ‘‘one shot.” 


Once a repeating AST is associated with an entry, attempts to issue 
subsequent one-shot ASTs on that entry return an error because the results 
are unpredictable. If you enable an entry without an associated AST, you 
can issue one-shot ASTs to process the buffered data one character at 

a time. You can associate a repeating AST with an entry at any time by 
reenabling the entry (or for keyboards, modifying the keyboard). However, 
any outstanding one-shot ASTs are processed first. 


Note that QIO modifiers enable you to purge the type-ahead buffer. If. 
you delete an entry and the type-ahead buffer is not empty, the deletion 
is deferred until the type-ahead buffer is empty. If an application wants to 
delete an entry immediately, it must first purge the buffer. 





2.7 intercepting Input 


You can issue one-shot ASTs on a channel that currently has no repeating 
AST associated with it. To “‘intercept’’ input, disable the associated AST 
(by reenabling the entry without the AST specification), then issue one 
shots. (Note that for a keyboard you can disable an AST by modifying the 
keyboard instead of reenabling it.) Later, you can reenable the repeating 
AST. : 


To intercept the input for an entry on a list, use the Get Next Input Token 
QIO; specify the type of input token IO$C_QV_ENAKB, IO$C_QV_ 
MOUSEMOV, or IO$C_ENABUTTON) and the channel with which the 
entry is associated. 


You can also use one shot ASTs to process input from within an AST (ASTs 
cannot be delivered in this case). An application can rely on the fact that a 
one shot AST with no associated AST delivers the input to the IOSB. With 
an event flag and the IOSB, the application can process the type-ahead 
buffer one character at a time from within the AST. 


The example in Appendix D contains instances of intercepting input. 





2.8 Defining Cursor Patterns 


The QIO interface enables you to associate a region of the screen with a 
specific cursor pattern. Use the QIO interface to change the shape and size 
of the cursor to reflect a change in functionality; for example, an editing 
cursor can take one shape while a menu selection cursor takes another. 
Again, the driver maintains an entry list to keep track of cursor patterns. 


Use the Define Pointer Cursor Pattern QIO to create a cursor pattern entry. 
When you create a cursor pattern entry, specify the following information: 


e The address of a bitmap image for the new cursor pattern. This bitmap 
image is a 16-word array on single-plane cursor systems or a 32-word 
array on multiplane cursor systems. The QVB contains a field that 
indicates whether you have a single-plane or multiplane system; use 
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the Get System Information QIO to access this field. The following 
section describes multiplane cursor patterns. 


e The address of a longword to contain a new cursor position. This 
optional parameter enables you to reposition the cursor. 


e The address of the cursor hot spot definition. The hot spot is the one 
position within the bitmap image of the cursor that is the actual cursor 
position. 


¢ Cursor style. This value defines how the cursor appears against the 
background of the screen. (It is ignored on multiplane cursor systems.) 


e Address of a screen rectangle values block that describes the region to 
be associated with the cursor pattern. . 


By default, an entry is placed at the top of the list. However, an application 
can determine the position of the entry in the list by specifying optional 
modifiers to the QIO. The modifiers can be used to perform the following 
functions: . 


° Place the entry last on the list (QV_LAST) 
e Delete the entry (QV_DELETE) 


As the pointer moves, the driver checks the pointer position against the 
region descriptors of the cursor pattern list entries. When the driver finds 
a region descriptor that contains the current pointer position, it changes the 
cursor pattern to the one associated with the region. 


Example 2-8 illustrates the typical assignment of a single-plane cursor. 
region pattern. (Appendix D of this manual shows this example in the 
context of a complete application program.) 


2.8.1 Multiplane Cursor Patterns 
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If your system uses a multiplane cursor, you can specify a 32-word array 
as a cursor pattern. Multiplane cursors consist of two planes. Typically, 
you use two planes to prevent the cursor from disappearing when it moves 
over varying backgrounds. To understand how the two planes work, think 
of the 32-word array as two 16-word arrays, array A and array B. 


The bit pattern in array A is determined as follows: 
¢ 1—Indicates that the corresponding pixel be filled. 


¢ 0 —Indicates that whatever is on the screen at the corresponding pixel 
should show through (remember, the cursor is overlaid on the screen). 


The bit pattern in array B uses the the bits set to 0 in array A as a mask: 
those corresponding bits are ignored in array B. The remaining bit pattern 
in array B is determined as follows: 
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Example 2-8 Assignment of a Single-Plane Cursor Region Pattern 


QVSCURSOR1: : initial 16 x 16 cursor 
+; "solid" pattern 
«WORD 4b1111111111111111 

» WORD 4b1111111111111111 

» WORD 4b1111111111111111 

.» WORD 4b1111111111111111 

.» WORD 4b1111111111111111 

«WORD 4b1111111111111111 

»WORD “b1111111111111111 

» WORD 4b1111111111111111 

.» WORD 4b1111111111111111 

«WORD 4b1111111111111111 

»WORD 4b1111111111111111 

.» WORD 4b1111111111111111 

. WORD 4b1111111111111111 

»WORD 4b1111111111111111 

» WORD 4b1111111111111111 

»WORD 4b1111111111111111 


REGION1: ; cursor region 1 
- LONG 20 3; lower left corner 
- LONG 20 
- LONG 300 ; upper right corner 


- LONG 300 


define cursor 1 
channel 

QIO function code 
driver function code 
cursor pattern 
associated region 

no error if set 


208: MOVL #IO$C_QV_SETCURSOR, RO 

$QIOW_S CHAN=CUR_CHAN1,- 
FUNC=#10$_SETMODE, - 
Pl =(RO),- 
P2=#QVSCURSOR1,- 
P6=#REGION1 

BLBS RO, 30$ 

BRW ERROR 


we Ne we Ne Ne we Ne 
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e 1—Indicates that the corresponding pixel be filled with the background 
color. 


¢ OQ —Indicates that the corresponding pixel be filled with the foreground 
color. 





2.9 Using an Alternate Windowing System 


NOTE: 


For flexibility, the QVSS driver supports a single private graphics 
application in addition to the default, VWS-supplied windowing package. 
That is, you can write an alternate windowing application that takes 
complete control of video memory and does not depend on VWS-supplied 
window or graphics services. 


To enable alternate windowing, before you invoke the STARTVWS.COM 
command procedure, modify the command procedure SYSTARTUP_ 
V5.COM to define the logical name UIS$SWS_ALTAPPL to ‘“TRUE.” 


This instructs the driver to reserve half of video memory for a private 
application. At the request of the private application, this part of video 
memory is mapped to the screen and becomes available to the application. 
All set mode functions issued by the application relate only to its private 
video memory. A user interface key (F3) on the keyboard allows an 
operator to switch dynamically between windowing systems. 


Private applications are device dependent; only one private application can 
be active at a time. | 





2.10 Drawing to the QVSS Screen 


To draw to the screen using the QVSS driver, follow these steps: 
1 Access the QOVB. 
2 Manipulate bits in video memory. 


3 Map the manipulated video memory to the screen. 


Section 2.2 describes how to access the QVB. The following sections 
describe how to manipulate bits and map video memory to the screen. 


2.10.1 Manipulating Bits in Video Memory 
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A QVSS application “‘draws’’ by setting bits directly in video memory. To 
access video memory, use the QVB$L_MAIN_VIDEOADDR address in the 
QVB. The application determines how to offset into video memory. When 
you manipulate memory, remember the following: 


¢ ach scanline of video memory is 1024 bits (128 bytes) wide. 


¢ There are 1024 scanlines in memory. 


NOTE: If you use an alternate windowing system, the accessible number of 


scanlines is effectively halved. 
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2.10.2 Mapping Video Memory to the Screen 


To map a scanline in memory to the screen, load an entry in the scanline 
map. The scanline map consists of word-length entries whose positions in 
the map correspond to line positions on the screen and whose contents are 
indices of scanline positions in video memory. The index of scanlines in 
memory starts at zero and is incremented by one for each scanline. 


Mapping with an Alternate Windowing System 


This scheme is straightforward unless you are using an alternate windowing 
system, in which case memory is split in half and shared by two systems. 
To ensure that you are mapping the correct portion of memory, calculate 
the correct scanline base in video memory. To obtain the correct scanline 
base, complete the following steps: 


1 Subtract the QVB$L_VIDEOADDR address from the QVB$L_MAIN_ 
VIDEOADDR address. 


2 Divide the result by 128 (number of bytes in a scanline). 


Add the base to any scanline index before you insert it as an entry in the 
scanline map. 
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2.11 Creating a QDSS Viewport 


The QDSS driver performs all viewport operations to the screen. If your 
application is not using the UIS windowing interface, it must create a 
viewport or use the systemwide viewport before it attempts to write to the 
screen. Example 2-12, later in this chapter, demonstrates how to access 
the systemwide viewport. | | 


To create a viewport, an application must perform the following steps: 
1 Assign the viewport a channel. 

2 Get a viewport ID. 

3 Define the location and size of the viewport. 


4 Start the viewport. 


The following sections describe how to perform each of these steps. 


2.11.1 Assigning a Viewport Channel 


Use the $ASSIGN system routine to obtain a unique channel for a 
viewport. The actual association of the viewport with the channel occurs 
when the application gets a viewport ID for the viewport. 


2.11.2 Getting a Viewport ID 


Use the Get Viewport ID QIO to get a viewport ID. One parameter of this 
QIO specifies the address of the longword to receive the ID. The ID stored 
at that address identifies which viewport is the object of all subsequent 
operations. The channel the application specifies in this QIO is associated 
with the viewport. 


2.11.3 Defining a Viewport 


A viewport is defined by one or more rectangular update regions. Update 
regions are defined in Update Region Definition (URD) buffers. Each URD 
buffer contains coordinate information that defines the dimensions, in 
pixels, of a rectangle and its location relative to the base of QDSS memory 
either onscreen or offscreen. (See Appendix B for detailed information 
about this data structure.) A viewport can be defined by one or more 
URDs. Figure 2-7 illustrates a 500- by 500-pixel viewport defined by a 
single URD and displays the contents of the associated definition buffer. 
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Figure 2-7 Viewport and Update Region Definition Buffer 


F 


X Y 


Pe ta 4 Lower Left Corner (URC) 


~~ (499,499) 
|_| | 499 | 499 Upper Right Corner (VRC) 


~ (0,0) 





| 50 | 100 | Absolute Base (ADC) 
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Note that the base is given in absolute coordinates and the two defining 
corners of the viewport are given in viewport relative coordinates. These 
coordinates become important when a viewport is divided into a number of 
rectangles and some (occluded) rectangles are stored in offscreen memory. 
Drawing operations use the relative coordinates to perform drawing, even 
when rectangles are not visible on the screen. 


To define a viewport, follow these steps: 


1. Allocate and initialize one or more URD buffers that describe the 
viewport’s size and relative position. 


2 Call the Define Viewport Region QIO once for each viewport, passing 
the URD (or array of URDs if the viewport is more than one rectangle). 


Parameters of the Define Viewport Region QIO specify the address and 
length of the viewport definition buffer and the viewport ID. 


To redefine a viewport, reinvoke the Define Viewport Region QIO with 
new coordinate information and the same channel and viewport ID. 


2.11.4 Starting the Viewport 
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When you define a viewport, it is in a “stopped” state. To permit 
operations to the viewport, you must explicitly start the viewport request 
queue with the Start Request Queue QIO. 


Example 2-9 creates and starts a 100-pixel square viewport with its 

lower left corner at the absolute device coordinate (10,10). Note that in 
FORTRAN, you must include the IODEF library to access the QIO function 
codes. 
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Example 2-9 Creating a Viewport 





PROGRAM CREATE_VIEWPORT 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE 'VWSSYSDEF’ 
INCLUDE '(SIODEF)’ 


INTEGER*2 CHAN _VP1, 
2 CHAN_VP2 


! Declare URDs 
INTEGER*2 URD1_VP1(6), 


2 URD1_VP2(6) 

! Load URD1_VP1 buffer 

URD1_VP1(1) = 0 ! lower left corner 
URD1_VP1(2) = 0 

URD1_VP1(3) = 99 ! upper right corner 
URD1_VP1(4) = 99 

URD1_VP1(5) = 10 ! absolute coordinate base 


URD1_VP1(6) 


tl 


10 


! define and start VP1 
CALL VIEWPORT (URD1_VP1, CHAN_VP1, VP1_ID) 


RARER KKK KEK KK KK 


! Viewport Subroutine 
LP RIKER KKKKKKEK KICK 


SUBROUTINE VIEWPORT (VP_URD, VP_CHANNEL, VIEWPORT_ID) 


IMPLICIT INTEGER*4(A~-Z) 
INCLUDE ‘VWSSYSDEF’ 
INCLUDE ’(SIODEF)’ 


INTEGER*2 VP_CHANNEL 


! Obtain a channel for the viewport 
CALL SYSSASSIGN (’SYSSWORKSTATION’, ! device name 
2 VP_CHANNEL,,; 7) ! channel 


! Get a viewport ID 

CODE = IO$_SENSEMODE 

STATUS = SYSSQIOW (, 

2 %VAL(VP_CHANNEL) , 
%VAL(CODE), 


channel 


2 

2 rere 

2 %VAL(IO$C_QD_GET_VIEWPORT_ID) 
2 VIEWPORT_ID, 
2 
2 
I 


—m eo 


%*VAL(4), 
rr) 
F (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


! Define the Viewport Region 
CODE = IO0$_SETMODE 
STATUS = SYSSQIOW (, 


2 %VAL(VP_CHANNEL) , ! channel 

2 %VAL(CODE), ! QIO function code 

2 re 

2 %VAL(IO$C_QD_SET_VIEWPORT_REGIONS), 

2 VP_URD, ! address of URD buffer 
2 %VAL(URDS$C_LENGTH) , ! length of URD buffer 
2 %VAL(VIEWPORT_ID),,) ! address of VP ID 

IF (STATUS .NE. 1) THEN 


CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


QIO function code 


address of ID buffer 
VP ID buffer length 





Example 2-9 Cont’d. on next page 
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Example 2-9 (Cont.) Creating a Viewport 











! Start the Viewport 
STATUS = SYSSQIOW (, 


2 %VAL(VP_CHANNEL) , ! channel 
2 %VAL(CODE), ! QIO function code 
2 rev 
2 “%*SVAL(IOSC_QD_START), ! QD function code 
2 %VAL(VIEWPORT_ID), ! address of ID buffer 
2 rrr) 
IF (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (%*VAL (STATUS) ) 
END IF 
RETURN 
END 


Drawing with the QDSS Driver 


The QDSS driver uses data structures known as drawing operation 
primitives (DOPs) to perform drawing operations. Your application loads 
a DOP with all the information necessary for the hardware to perform a 
drawing operation. Typically, a DOP contains the type of operation to 
perform (that is, draw a line, draw text, and so on), the number of times to 
perform it, and any coordinates needed to perform the operation. 


You must allocate storage for DOPs, insert DOPs on the request queue 

to execute them, and reuse the storage with the return queue. If your 
application uses the UIS windowing environment, you can perform all 
three of these functions with UISDC routines. However, if your application 
does not use the UIS windowing environment, the application must 
manage DOP storage and insert DOPs on the request queue. 


Chapter 5 describes how to perform drawing with DOPs. 





Using Bitmaps 
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Although the QDSS driver does not support direct manipulation of the 
onscreen bitmap, it permits you to copy bitmap images from processor 
memory to onscreen and offscreen memory and from onscreen and 
offscreen memory to processor memory. 


The driver provides the following QIOs for manipulating bitmaps: 


¢ Write Bitmap—Copies a bitmap from processor memory to QDSS 
screen memory and performs bitmap-to-bitmap transfers (onscreen-to- 
offscreen and offscreen-to-onscreen). 


¢ Read Bitmap—Copies a bitmap from QDSS memory to processor 
memory and performs bitmap-to-bitmap transfers (onscreen-to- 
offscreen and offscreen-to-onscreen). 


¢ Load Bitmap—Loads a bitmap to be used by a text or fill pattern 
drawing operation from processor memory into the reserved bitmap 
area of offscreen memory (see Figure 1-4). This QIO returns a bitmap 
ID that the DOPs use to reference the bitmap. Bitmaps loaded by this 
QIO must follow certain criteria; see Chapter 4 for details. The UISDC 
interface also provides a Load Bitmap function. (See Chapter 5.) 
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To draw an image, complete the following steps: 
1 Build the image in processor memory. 


2 Use the Write Bitmap QIO to load the image into QDSS memory. 


To store an image in processor memory, use the Read Bitmap QIO to copy 
the bitmap from QDSS memory to processor memory. (Complete this 
process for occluded viewport regions when offscreen memory is full; see 
Section 2.18.) 


Use the Load Bitmap QIO to load a bitmap for use with a DOP. 


Example 2-10 later in this chapter illustrates the use of the Write Bitmap 
QIO to copy a region from onscreen memory into offscreen memory 
(bitmap-to-bitmap transfer). 





2.14 Synchronizing Viewport Activity 


Because DOPs are queued asynchronously for processing and execution, 
you must take special action to synchronize activity on a viewport. 


Figure 2-8 illustrates the three DOP states: 
e In the queue, waiting to be processed 
e Currently being processed by the driver 


¢ Completed and on the screen 


Figure 2~8 Synchronizing Viewport Activity 


In Queue Processed by On the Screen 
Driver 


LS] 9 
RS i 
0 


The driver can process a number of DOPs at a time. To synchronize 
activity, manipulate the queue and be aware of whether the driver is 
currently processing DOPs. 








ZK-5349-86 


2-29 


Programming to the Driver 


2-30 


Synchronization QiOs 
The QIO interface provides the following QIOs for synchronization: 


¢ Stop Request Queue—Immediately halts the processing of the request 
queue and waits for whatever is currently being processed to complete 
before returning. 


¢ Start Request Queue—Restarts processing on a stopped request queue. 


¢ Suspend Request Queue—Immediately halts the processing of the 
request queue but does not wait for whatever is currently being 
processed to complete before returning. 


¢ Resume Request Queue—Resumes processing on a suspended request 
queue. 


¢ Hold Viewport Activity—Does not permit any viewport except the 
systemwide viewport to write to the screen (processing continues). 


¢ Release Hold—Releases the hold on viewport activity. 


¢ Insert DOP—Permits an application to insert a DOP on the request 
queue and waits for completion (essentially performs a synchronous 
DOP). 


Request Queue Interface DOPs 


In addition to the QIOs, the request queue interface permits you to submit 
the following DOPs: 


¢ Stop Viewport Activity—Halts the queue and waits for any DOPs 
currently processing to complete. This differs from the Stop Request 
Queue QIO in that all DOPs inserted before this one are guaranteed to 
execute before the queue is stopped. 


e Start Viewport Activity—Restarts processing on a stopped request 
queue. 


e Suspend Viewport Activity—Halts the queue but does not wait for any 
DOPs currently processing to complete. This differs from the Suspend 
Viewport Activity QIO in that all DOPs inserted before this one are 
guaranteed to execute before the queue is stopped. 


e Resume Viewport Activity—Resumes processing on a suspended 
request queue. 


A Stop also differs from a Suspend in that a Stop issued on a stopped 
Request Quest waits for the queue to restart, then takes effect, while a 
Suspend issued on a suspended viewport is ignored. The Stop is thus 
useful for synchronizing multiprocess windowing activity on a single 
viewport. To guarantee that no other process accesses the viewport, 

a process can issue a Stop before it attempts any windowing activity 
(redefining URDs and so forth). When control returns from the Stop, it 
is clear that no other process DOPs can execute on the viewport and any 
DOPs that were processing have completed. 


Note that if you issue a Stop Request Queue QIO to an already stopped 
viewport, the QIO will not complete until the viewport is started by an AST 
routine or another process. However, if you issue a Stop Request Queue 
QIO to a suspended viewport, the Stop Request Queue QIO will complete. 
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2.15 Handling Occlusion 


In multiviewport systems, two or more viewports might overlap. This 
overlapping is called occlusion. Figure 2-9 illustrates one viewport (VP_A) 
occluding another (VP_B). 


Figure 2-9 Occluded Viewport 


VP_B u—». 


Occluded region of VP_B 
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Only one viewport can display the overlapped area of the bitmap at a 
time. If your application permits occlusion, it must be able to handle any 
operations directed to an occluded viewport region. It does this by moving 
the occluded region of the viewport into offscreen memory and performing 
any necessary operations there. If that portion of the screen becomes 
available for display later, you can pop the viewport, or copy the up-to-date 
region back to the screen. The following sections describe how to handle a 
simple case of occlusion. 


2.15.1 Redefining Viewports 


An application uses the update region definition buffers to handle 
occlusion. A viewport originally defined as one rectangle with a single 
URD can be redefined as a number of rectangles (viewport regions) with 
one URD for each rectangle. The URDs provide both the absolute position 
of the rectangle in QDSS memory and the viewport-relative coordinates of 
the rectangles in relation to one another. 


Use the Define Viewport Region QIO to redefine a viewport. You can use a 
negative Y coordinate to redefine an occluded region in offscreen memory; 
because drawing operations use viewport-relative coordinates, the drawing 
is performed properly. You must ensure that the negative Y coordinate 
you use falls within the range of the free_1 area of offscreen memory (see 
Figure 1-4). 


Figure 2-10 illustrates partitioning of an occluded viewport. In this 
example, the viewport is divided into three rectangles (A, B, and C). 
The minimum, maximum, and base (X,Y) coordinate pairs are stored in 
three definition buffers. 
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The base coordinates of each accessible rectangle are in absolute device 
coordinates relative to the base of display memory (0,0). A base value 
with two positive coordinates indicates that the rectangle is in onscreen 
display memory. A base value with a negative Y coordinate and a positive 
X coordinate indicates that the rectangle is in offscreen memory. A base 
value of (-1,-1), for instance, indicates that the rectangle is on the deferred 
queue; see Section 2.18 for information about the deferred queue. Note 
that rectangle A is redefined to be in offscreen memory. 


Figure 2-10 Redefining Viewports with URDs 


Associated URDs 
X Y 


omy 
fa J 
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2.15.2 Securing Exclusive Access to the Bitmap 
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An application secures exclusive access to the bitmap to guarantee that two 
or more overlapping viewports do not attempt to write simultaneously to 
the same piece of the display. Before it creates a viewport, your application 
should determine whether another viewport already exists in the area of the 
screen where the viewport will be created. (The application is responsible 


_ for tracking each viewport on the screen.) 


To secure exclusive access to a viewport bitmap follow these steps: 


1 Use the Stop Request Queue QIO to stop activity on the existing 
viewport to ensure a known state for the subsequent steps. 


2 Use the Define Viewport Region QIO to redefine the regions of the 
existing viewport. 


3 Use the Write Bitmap or Read Bitmap QIO to copy the to-be-occluded 
region of the existing viewport to offscreen memory. 
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4 Update the URD definition of the existing viewport to reflect its new 
state. Specify a negative Y coordinate in the base value of the URD 
to redefine the occluded region to be offscreen. (The negative Y value 
must fall within the range of the free area of offscreen memory shown 
in Figure 1-4). Drawing can still be performed to offscreen memory. 


5 Use the Start Request Queue QIO to restart the viewport. 


Now you can create the new viewport on screen and start drawing 
operations on it. 


Example 2-10 illustrates how one viewport occludes another. Exclusive 
access to the bitmap is guaranteed before the second viewport is created. 
The occluded region of the existing viewport is copied into the offscreen 
memory free area at (0,-200). Note that the transfer parameter block (TPB) 
is loaded by the predefined structure in the VWSSYSDEFEF file. 
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PROGRAM CREATE _VIEWPORT 
IMPLICIT INTEGER* 4 (A-Z) 
INCLUDE ‘VWSSYSDEF’ 
INCLUDE /’(SIODEF)’ 


INTEGER*2 CHAN_VP1, 
2 CHAN_VP2 


! Declare TPB 
INTEGER*2 TPB(13) 


! Declare URDs 
INTEGER*2 URD1_VP1(6), 
2 URD1_VP2(6) 


! Load URD1_VP1 buffer 


URD1_VP1(1) = 0 ! lower left corner 
URD1_VP1(2) = 0 

URD1_VP1(3) = 99 ! upper right corner 
URD1_VP1(4) = 99 

URD1_VP1(5) = 10 ! absolute coordinate base 
URD1_VP1(6) = 10 

! Load URD1_VP2 buffer 

URD1_VP2(1) = 0 ! lower left corner 
URD1_VP2(2) = 0 

URD1_VP2(3) = 99 ! upper right corner 
URD1_VP2(4) = 99 

URD1_VP2(5) = 60 ! absolute coordinate base 
URD1_VP2(6) = 60 


! Define and start VP1 
CALL VIEWPORT (URD1_VP1, CHAN_VP1, VP1_ID) 


! Stop VP1 
CODE = I0$_SETMODE 
STATUS = SYSSQIOW (, 


2 %VAL(CHAN_VP1), ! channel 

2 %VAL(CODE) , ! QIO func 
2 eee 

2 %VAL(IOSC_QD_STOP), ! QD funct 
2 %VAL(VP1_ID), ! address 

2 tre.) 

IF (STATUS .NE. 1) THEN 


CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


! Load TPB for occluded rectangle 
CALL LOAD_TPB (TPB) 


! Copy occluded rectangle into offscreen memory 
CODE = I0$_QDWRITE 
STATUS = SYSSQIOW (, 
2 %VAL(CHAN_VP1), 
2 %VAL(CODE), 
2 vrrrege 
2 TPB, ! 
2 %VAL(TPBSC_BITMAP_XFR_LENGTH), ) 
IF (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (%*VAL (STATUS) ) 
END IF 


! Update regions of VP1 
CALL UPDATE_REGIONS (CHAN _VP1, VP1_ID) 
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! Restart VP1 
CODE = IOS_SETMODE 
STATUS = SYSSQIOW (, 


2 %VAL(CHAN_VP1), ! channel 

2 %VAL(CODE), ! QIO function code 

2 tre 

2 %VAL(IOSC_QD_START), ! QD function code 

2 %*VAL(VP1_ID), ! address of ID buffer 
2 rere) 

IF (STATUS .NE. 1) THEN 


CALL LIB$SIGNAL (%VAL (STATUS) ) 
END IF 


! Define and start VP2 
CALL VIEWPORT (URD1_VP2, CHAN _VP2, VP2_ID) 


KREKKKKKKKKKKKKKKKK KKK KEK 


! 
! * LOAD TPB SUBROUTINE * 
! 


KKEHKKIKKEEKKEKEKKKKEKKKKREK 


SUBROUTINE LOAD _TPB (TPB) 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE 'VWSSYSDEF’ 


! Associate the predefined structure w/ TPB 
RECORD /TPB_STRUCTURE/ TPB 


! Load values 
TPB.TPBSB_TYPE TPBSC_BITMAP_XFR ! type 
TPB.TPBSB_SIZE = TPB$C_LENGTH 
TPB.TPBSW_X_SOURCE = 60 
TPB.TPBSW_Y_SOURCE = 60 
TPB.TPBSW_WIDTH = 50 
TPB.TPBSW_HEIGHT = 50 
TPB.TPBSW_X_TARGET = 0 
TPB.TPBSW_Y_TARGET = -200 


x of lower left corner 
y of lower left corner 
width of source 

height of source 

x of lower left corner 
y of lower left corner 


a eS ee ee ee 


RETURN 
END 


PRI RRR RIKKI KIRKE RRR KKK RRR ER 
! * UPDATE REGION SUBROUTINE * 
! 


KEKKKKEKKEKKKIKKEKKKKRKKKEKK KKK ER 


SUBROUTINE UPDATE_REGIONS (VP_CHANNEL, VIEWPORT_ID) 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE ‘VWSSYSDEF’ 

INCLUDE '(SIODEF) ‘ 


! Declare URD 
INTEGER*2 URD(18) 


! Load URD buffer 
! First rectangle 


URD(1) =O © ! lower left corner 

URD(2) = 0 

URD(3) = 99 ! upper right corner 
URD(4) = 49 

URD(5) = 10 ! absolute coordinate base 
URD(6) = 10 
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! Second rectangle 
URD(7) = 0 ! lower left corner 
URD(8) = 49 
URD(9) = 49 ! upper right corner 
URD(10) = 99 
URD(11) = 10 .! absolute coordinate base 
URD(12) = 59 
! Third rectangle 
URD(13) = 49 ! lower left corner 
URD(14) = 49 
URD(15) = 99 ! upper right corner 
URD(16) = 99 
URD(17) = 0 ! absolute coordinate base 
URD(18) = -200 ! (offscreen) 
CODE = I0$_SETMODE 
STATUS = SYSSQIOW (, 
2 %VAL(VP_CHANNEL) , ! channel 
2 %VAL(CODE), ! QIO function code 
2 ree 
2 %VAL(IO$C_QD_SET_VIEWPORT_REGIONS), 
2 URD, ! address of URD buffer 
2 %VAL(3 * URDSC_LENGTH), ! length of URD buffer 
2 %VAL(VIEWPORT_ID)-,,) ! address of VP ID 
IF (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (*VAL (STATUS) ) 
END IF 
RETURN 
END 


2.15.3 Popping an Occluded Viewport 


Bringing an occluded viewport into full view onscreen is referred to as 
popping a viewport. Popping a viewport involves copying the occluding 
region into offscreen memory and the occluded region from offscreen 
memory onto the screen. To pop a viewport, an application must take the 
following steps: 
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Stop activity on the occluding viewport. 

Copy the occluding region into offscreen memory. 

Redefine the occluding viewport URDs. 

Restart the occluding viewport. 

Stop activity on the occluded viewport. 

Copy the occluded region from offscreen memory onto the screen. 
Redefine the occluded viewport URDs. 


Restart the (formerly) occluded viewport. 


Example 2-11 illustrates popping a viewport. 
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PROGRAM POP 

IMPLICIT INTEGER*4(A-Z) 
INCLUDE ‘VWSSYSDEF’ 
INCLUDE ‘’(SIODEF)’ 


INTEGER*2 CHAN _VP1, 
2 CHAN_VP2 


! Declare TPBs 
INTEGER*2 TPB1(13), 
2 TPB2(13), 
2 TPB3(13) 


! Declare URDs 
INTEGER*2 URD1_VP1(6), 


2 URD1_VP2(6) 

! Load URD1_VP1 buffer 

URD1_VP1(1) = 0 ! lower left corner 
URD1_VP1(2) = 0 

URD1_VP1(3) = 99 ! upper right corner 
URD1_VP1(4) = 99 

URD1_VP1(5) = 10 ! absolute coordinate base 


URD1_VP1(6) = 10 


! Load URD1_VP2 buffer 


URD1_VP2(1) = 0 ! lower left corner 
URD1_VP2(2) = 0 

URD1_VP2(3) = 99 ! upper right corner 
URD1_VP2(4) = 99 

URD1_VP2(5) = 60 ! absolute coordinate base 
URD1_VP2(6) = 60 


! Define and start two overlapping viewports 


! Stop VP2 (the occluding viewport) 

CODE = IO$_SETMODE 

STATUS = SYSSQIOW (, 

2 %SVAL(CHAN_VP2), 
%VAL(CODE), 


channel 
QIO function code 


om om 


2 
2 err 

2 %VAL(IO$SC_QD_STOP), QD function code 
2 

2 

I 


address of ID buffer 


%VAL(VP2_ID), 
rrr) 
F (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


! Load TPB for occluded rectangle 
CALL LOAD_TPB2 (TPB2) 


! Copy occluding region into offscreen memory 
CODE = I0$_QDWRITE 
STATUS = SYSSQIOW (, 


2 %VAL(CHAN_VP2), ! channel 

2 %VAL(CODE), ! QIO function code 
2 rrr@rve?e 

2 TPB2, ! transfer block 

2 %VAL(TPB$C_BITMAP_XFR_LENGTH) , ) 

IF (STATUS .NE. 1) THEN 


CALL LIB$SIGNAL (%VAL (STATUS) ) 
END IF 


! Update regions of VP2 
KEY = 2 
CALL UPDATE_REGIONS (CHAN_VP2, VP2_ID, KEY) 
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! Restart VP2 
CODE = I0$_SETMODE 
STATUS = SYSSQIOW (, 
2 %VAL(CHAN_VP2), 
2 %VAL(CODE), 
2 ere 
2 %VAL(IO$C_QD_START), 
2 %*VAL(VP2_ID), 
2 ree) 
IF (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (%*VAL (STATUS) ) 
END IF 


{ Stop VP1 (the occluded viewport) 
CODE = I0$_SETMODE 
STATUS = SYSSQIOW (, 
2 %VAL(CHAN_VP1), 
2 %VAL( CODE) , 
2 ere 
2 %VAL(IO$C_QD_STOP), 
2 %VAL(VP1_ID), 
2 ree) 
IF (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (%*VAL (STATUS) ) 
END IF 


! Load TPB for occluded rectangle 
CALL LOAD_TPB3 (TPB3) 


-_ 


channel 
QIO function code 


QD function code 
address of ID buffer 


channel 
QIO function code 


QD function code 
address of ID buffer 


t Copy offscreen rectangle into screen memory 


CODE = I0$_QDWRITE 

STATUS = SYSSQIOW (, 

2 %VAL(CHAN_VP1), 
%VAL(CODE) , 


rrrrre 


! channel 
! QIO function code 


! transfer block 


%VAL(TPBSC_BITMAP_XFR_LENGTH), ) 


2 
2 
2 TPB3, 
2 
IF (STATUS .NE. 1) THEN 


CALL LIB$SIGNAL (%VAL (STATUS) ) 
END IF 


! Update regions of VP1 
KEY = 3 


CALL UPDATE_REGIONS (CHAN_VP1, VP1_ID, KEY) 


! Restart VP1 
CODE = I0$_SETMODE 
STATUS = SYSSQIOW (, 


2 %VAL(CHAN_VP1), 

2 %VAL(CODE) , 

2 ree 

2 %VAL(IO$C_QD_START), 
2 %VAL(VP1_ID), 

2 rere) 

IF (STATUS .NE. 1) THEN 


CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


YP HRA KIKKRHEKKEKEKRKKEKEKKEKEK 


! * LOAD TPB2 SUBROUTINE * 2 


YP RRR KREKEEKEKKKEKIEKEKEKKEK 
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SUBROUTINE LOAD_TPB2 (TPB) 
IMPLICIT INTEGER* 4(A-Z) 
INCLUDE ‘VWSSYSDEF’ 


! Associate the predefined structure w/ TPB 
RECORD /TPB_STRUCTURE/ TPB 


{ Load values 


TPB. TPBS$B_TYPE = TPBSC_BITMAP_XFR ! type 

TPB.TPBSB_SIZE = TPBSC_LENGTH 

TPB.TPBSW_X_SOURCE = 60 ! x of lower left corner 
TPB.TPBSW_Y_SOURCE = 60 ! y of lower left corner 
TPB.TPBSW_WIDTH = 50 ! width of source 
TPB.TPBSW_HEIGHT = 50 ! height of source 
TPB.TPBSW_X_TARGET = 0 ! x of lower left corner 
TPB.TPBSW_Y_TARGET = -500 ! y of lower left corner 
RETURN 

END 


KREKKKKKKKKEKKKKKRKKKKRKRKEK 


{ * 
! * LOAD TPB3 SUBROUTINE * 3 
! * 


KRRKEKKEKKKEKKEKKKKEKKKKKKIK 


SUBROUTINE LOAD_TPB3 (TPB) 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ‘VWSSYSDEF’ 


! Associate the predefined structure w/ TPB 
RECORD /TPB_STRUCTURE/ TPB 


! Load values 
TPB.TPBSB_TYPE = TPBSC_BITMAP_XFR ! type 
TPB.TPBSB_SIZE = TPBSC_LENGTH 
TPB.TPBSW_X_SOURCE = 0 
TPB.TPBSW_Y_SOURCE = -200 
TPB.TPBSW_WIDTH = 50 
TPB.TPBSW_HEIGHT = 50 
TPB.TPBSW_X_TARGET = 60 
TPB,.TPBSW_Y_TARGET = 60 


x of lower left corner 
y of lower left corner 
width of source 
height of source 
x of lower left corner 
y of lower left corner 


ee ae a ee ee) 


RETURN 
END 


KHKKIKK KIKI KKKEK KEKE KIREKKEKEKK 


t 
! * UPDATE REGION SUBROUTINE * 
! 


KKEKKKKKKKRKKKRKKKRKKKKRKR KKK KKK 


SUBROUTINE UPDATE_REGIONS (VP_CHANNEL, VIEWPORT_ID, KEY) 
IMPLICIT INTEGER*4(A-Z) 

INCLUDE '‘VWSSYSDEF’ 

INCLUDE ' ($IODEF)’ 


! Declare URD 
INTEGER*2 URD(18) 


! Assume long URD 
URD_LENGTH = (3 * URDSC_LENGTH) 


! Key determines which URD is loaded 
IF (KEY .EQ. 1) THEN 


ELSE IF (KEY .EQ. 2) THEN 
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! Redefine VP2 for occlusion 
! First rectangle 


URD(1) = 0 ! lower left corner 

URD(2) = 0 

URD(3) = 49 { upper right corner 
URD(4) = 49 

URD(5) = 0 { absolute coordinate base 
URD(6) = -500 ! (offscreen) 

! Second rectangle 

URD(7) = 0 ! lower left corner 

URD(8) = 50 

URD(9) = 99 ! upper right corner 
URD(10) = 99 

URD(11) = 60 ! absolute coordinate base 


URD(12) = 110 
! Third rectangle 


URD(13) = 50 ! lower left corner 
URD(14) = 0 

URD(15) = 99 { upper right corner 
URD(16) = 49 

URD(17) = 110 ! absolute coordinate base 
URD(18) = 60 


ELSE IF (KEY .EQ. 3) THEN 


! Redefine VP1 for pop 
t lower left corner 


URD(1) = 0 
URD(2) = 0 
URD(3) = 99 ! upper right corner 
URD(4) = 99 
URD(5) = 10 ! absolute coordinate base 
URD(6) = 10 
URD_LENGTH = URDS$C_LENGTH 

ELSE 

END IF 


CODE = I0$_SETMODE 
STATUS = SYSSQIOW (, 


2 %VAL(VP_CHANNEL) , 3 ! channel 
2 %VAL(CODE), ! QIO function code 
2 ere 
2 *VAL(IOSC_QD_SET.VIEWPORT_REGIONS), 
2 URD, ! address of URD buffer 
2 %*VAL(URD_LENGTH), ! length of URD buffer 
2 %VAL(VIEWPORT_ID),,) ! address of VP ID 
IF (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (%*VAL (STATUS) ) 
END IF 
RETURN 
END 








2.16 Deleting a Viewport 


When you delete a viewport, synchronization of activity is important. 
Your application must guarantee that all drawing activity to a viewport is 
completed before the viewport is deleted. Once drawing is completed, you 
can deassign the associated channel to ensure that nothing else is written to 
the viewport. Finally, you can erase the viewport. The following sections 
describe each procedure. 
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2.16.1 Synchronizing Viewport Deletion 


Before you deassign a channel, you must ensure that all drawing to a 
viewport is complete, as follows: 


1 


Issue a Stop Viewport Activity DOP with the Insert DOP QIO (the 
QDWRITE function code with the IO$M_QD_INSERT_DOP modifier) 
to stop pending operations either on the DOP request queue or in 
progress before the delete. This QIO waits for the stop to occur before 
returning control, which accounts for the lag time in processing DOPs. 
If you do not wait for completion, you might delete the viewport while 
DOPs are on the queue. 


2 Use the $DASSGN system service to deassign the associated channel. 


2.16.2 Erasing a Viewport 


To erase a viewport, use the Fill Polygon DOP to draw a background- 
colored rectangle over the viewport. The channel of the viewport to be 
erased is already disassociated. You must use the systemwide viewport to 
perform this operation as follows: 


Assign a channel for the systemwide viewport. 


Obtain the system information block using the Get System Information 


QIO 
Extract the systemwide viewport ID from the system information block. 


Use the Fill Polygon DOP to draw a background-colored rectangle over 
the viewport (see Chapter 5 for details about DOPs). You must have 
the systemwide viewport ID to perform this DOP on the systemwide 
viewport. 


Example 2-12 illustrates deleting a viewport. 
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PROGRAM DELETE VIEWPORT 
IMPLICIT INTEGER*4(A-Z) 


INCLUDE 


'VWSSYSDEF’ 


INCLUDE '(SIODEF)’ 


t Declare 


external macro routine 


EXTERNAL DOPSINSQUE 


INTEGER* 2 
2 


{ Declare 
INTEGER* 2 


! Declare 
INTEGER*2 


! Declare 
INTEGER* 4 


CHAN_VP1, 
CHAN_SYS 


TPB 
TPB( 13) 


URD 
URD1_VP1(6) 


QDB descriptor and buffer 
QDB_DESC(2) 


! Load URD1_vP1 buffer 


URD1_VP1(1) = 0 ! lower left corner 
URD1_VP1(2) = 0 

URD1_VP1(3) = 99 ! upper right corner 
URD1_VP1(4) = 99 

URD1_VP1(5) = 10 ! absolute coordinate base 
URD1_VP1(6) = 10 . 


! Define and start VP1 
CALL VIEWPORT (URD1_VP1, CHAN_VP1, VP1_ID) 


! Draw to 


the viewport 


YR KEK KEKIKKEKEKEKK KKK 


! Delete the Viewport 
LERRKRKEKKKKKEKEKKHEKKK KKK K 


! Synchronize the deletion 
! get a Stop DOP for VP1 


SIZE = 


(DOP$C_LENGTH) ! 


calculate size 


CALL GET_DOP (VP1_ID, SIZE, DOP2) 


! Call the Stop subroutine 


CALL STOP_ 


2 
2 


VP (%VAL(DOP2), ! 
SIZE, ! 
VP1_ID) ! 


DOP address, by 
DOP size 
viewport ID 


value 


! Insert the DOP using Insert DOP QIO 


CODE = 


(IO$_QDWRITE .OR. IO$M_QD_INSERT_DOP) 


STATUS = SYSSQIOW (, 


2 %VAL(CHAN_VP1), ! channel 
2 %VAL(CODE);y,77 ! QIO function code 
2 DOP2, ! DOP address 
2 %SVAL(SIZE), ! DOP size 
2 %SVAL(VP1_ID),,,/) ! VP ID 
IF (STATUS .NE. 1) THEN 
CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


! Deassign the viewport channel 


CALL SYSSDASSGN (CHAN_VP1) t 


channel 


! Obtain a channel for the systemwide VP 


CALL SYSSASSIGN (‘’SYSSWORKSTATION’, ! 


2 


device name 


CHAN_SYS,,) ! channel 
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! Get the systemwide viewport ID 

! Get the QDB 

CODE = I0$_SENSEMODE 

STATUS = SYSSQIOW (, 

2 %VAL(CHAN_SYS), ! channel 
i] 


2 %VAL(CODE), QIO function code 

2 ver 

2 %VAL(IO$C_QV_GETSYS), 

2 QDB_DESC,,,,) ! address of descriptor 
IF (STATUS .NE. 1) THEN 


CALL LIBSSIGNAL (%VAL (STATUS) ) 
END IF 


! Extract the ID from the QDB 
SYS_ID = EXTRACT_SYS_ID (%*VAL(QDB_DESC(2))) ! pass address by value 


! Get a Fill Polygon DOP 
SIZE = (DOP_POLY$C_LENGTH) ! calculate size 
CALL GET_DOP (SYS_ID, SIZE, DOP3) 


! Call the Fill Polygon subroutine to erase VP1 border 


CALL F_POLY (%*VAL(DOP3), ! DOP address, by value 
2 %VAL(DOP3+DOPSC_LENGTH) , ! var. block address 

2 SIZE) ! DOP size 

! Queue the DOP by calling a MACRO subroutine 

CALL DOPSINSQUE (%VAL(DOP3), ! DOP address, by value 


2 SYS_ID) ! viewport ID 


4 RAKE KKKKKKKKKR KKK K 
t Get DOP Subroutine 
! 


FOI III OO IO IOI IOI IK 
SUBROUTINE GET_DOP (VIEWPORT_ID, SIZE, DOP) 
IMPLICIT INTEGER*4(A-Z) 


! Declare external macro routine 
EXTERNAL DOPSREMQUE 


DOP = DOPSREMQUE (VIEWPORT_ID, 
2 SIZE) 


! If none on return queue, calculate size and allocate one. 
IF (DOP .EQ. 0) THEN 
CALL TEST_SIZE (%*VAL(VIEWPORT_ID), ! viewport ID > return Q 
2 SIZE) 
! Allocate appropriate size DOP 
CALL LIBSGET_VM (SIZE, 
2 DOP) 
END IF 


RETURN 
END 


PFO IR KOR IK R RIRIIKRK IK 
{ * TEST_SIZE SUBROUTINE * 
! 


KEKKKKEKKKEKEKKKERKKKKKK KKK K 


SUBROUTINE TEST SIZE (REQ,SIZE) 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ’VWSSYSDEF’ 


! Associate the predefined structure w/ REQ 
RECORD /REQ_STRUCTURE/ REQ 
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IF (SIZE .GT. REQ.REQSW_SMALL_DOP_SIZE) THEN 
SIZE = REQ.REQSW_LARGE_DOP_SIZE 

ELSE 
SIZE = REQ.REQSW_SMALL DOP_SIZE 

END IF 


RETURN 
END 


KHER KKK KEEKKKK KEKE EK 


,] 
! * EXTRACT SYS_ID SUBROUTINE * 
! KKK KKKKEKHIKEKEKKEKEKEKKKEKKEKKREKRE 


FUNCTION EXTRACT _SYS_ID (QDB) 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE 'VWSSYSDEF’ 


! Associate the predefined structure w/ QDB 
RECORD /QVB_QDSS_STRUCTURE/ QDB 


EXTRACT_SYS_ID = QDB.QDB$L_SYSVP 


RETURN 
END 


PRR KEKE KHIR KKK KKK KK 


{ * STOP_VP SUBROUTINE * 
DIOR IOI IO IO RK KR KK 


SUBROUTINE STOP_VP (DOP, SIZE, VIEWPORT_ID) 
IMPLICIT INTEGER*4(A~Z) 
INCLUDE 'VWSSYSDEF’ 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Load the Common block 
DOP.DOPSW_SIZE = SIZE 
DOP.DOPSW_FLAGS = 0 
DOP.DOP$W_MODE = WRITSM_NO_SRC_COMP + 10 
DOP.DOPS$L_MASK = -1 
DOP.DOP$L_SOURCE_INDEX = -1 
DOP.DOP$L_FCOLOR = 253 
DOP.DOP$L_BCOLOR = 252 
DOP.DOPSW_VP_MAX_X = 99 
DOP. DOP$W_VP_MAX_Y = 99 
DOP.DOP$W_DELTA_X = 0 
DOP.DOPSW_DELTA_Y = 0 
DOP.DOP$W_VP_MIN_X = 0 
DOP.DOP$W_VP_MIN_Y = 0 


! Load the Stop values 
DOP.DOPSW_ITEM_TYPE = DOPS$C_STOP 
DOP.DOPSW_OP_COUNT = 1 
DOP.DOP$L_DRIVER_VP_ID = VIEWPORT_ID 


RETURN 
END 


KKKKKEKEKKKEKKKKKE KK KEK 


! 
! * F POLY SUBROUTINE * 
t 


KRKKKKKEKKKEKEKKKKKKKRK KK 


SUBROUTINE F_POLY (DOP, DOP_VAR, SIZE) 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ‘'VWSSYSDEF’ 


Example 2-12 Cont'd. on next page 
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! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Associate the predefined variable structure w/ DOP_VAR 
RECORD /DOP_POLY_ARRAY/ DOP_VAR 


{ Load the Common block 

DOP.DOPSW_SIZE = SIZE 

DOP.DOPS$W_FLAGS = 0 

DOP.DOPSW_MODE = WRITSM_NO_SRC_COMP + 10 
DOP.DOP$L_MASK = -1 
DOP.DOPSL_SOURCE_INDEX = -1 
DOP.DOPSL_FCOLOR = 252 

DOP.DOPS$L_BCOLOR = 252 


! Load the POLYGON values 

DOP. DOPSW_ITEM_TYPE = DOPS$C_FILL_POLYGON 
DOP.DOPSW_OP_COUNT = 1 
DOP.DOP$L_BITMAP_ID = 0 ! no bitmap 


DOP_VAR.DOP_POLY$W_LEFT_X1 = 10 
DOP_VAR.DOP_POLYS$W_LEFT _Y1 = 10 
DOP_VAR.DOP_POLYSW_LEFT_X2 = 10 
DOP_VAR.DOP_POLY$W_LEFT Y2 = 110 
DOP_VAR.DOP_POLYSW_RIGHT_X1 = 110 
DOP_VAR.DOP_POLYSW_RIGHT_Y1 = 10 
DOP_VAR.DOP_POLY$W_RIGHT_X2 = 110 
DOP_VAR.DOP_POLYS$W_RIGHT_Y2 = 110 
RETURN 

END 








.17 Moving a Viewport 


The QDSS driver does support moving a viewport or changing its size. 
However, an application can move a viewport as follows: 


1 Copy the contents of the old viewport to an area in the offscreen 
bitmap. 


2 Delete the old viewport. 
3 Create a new viewport. 


4 Copy the data from the offscreen bitmap to the new viewport. 





.18 Using the Deferred Queue 


An application is responsible for tracking offscreen memory use. When 

a viewport is occluded and the free area of offscreen memory is already 
full of occluded regions, you can ensure a drawing operation for the region 
only by placing the region on the deferred queue as follows: 


1 To save the state of the region until update, use the Read Bitmap QIO 
to copy the region to processor memory. 
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2 Use the Define Viewport Region QIO to redefine the region, setting the 
absolute base coordinates to (-1,-1). When you place a region on the 
deferred queue, the relative coordinates are used only to inform the 
driver that operations for the region are to be stored on the deferred 
queue. 


Before you use the deferred queue, call the Notify Deferred Queue Full 
QIO. This QIO enables you to notify an application when the deferred 
queue is full. (It prevents a deferred region from consuming too much 
memory.) 


Your application should execute operations stored on the deferred queue 
either when QDSS memory becomes available or when it is notified that 
the queue is full. To execute an operation on the deferred queue, follow 
these steps: 


1 Use the Write Bitmap QIO to copy the region back into offscreen 
memory. 


Use the Define Viewport Region QIO to redefine the region. 


Use the Execute Deferred Queue QIO to execute operations stored on 
the queue. 


If no memory is available when the queue is full, swap another region 
out of offscreen memory and onto the deferred queue until the queue is 
executed. 


Note that if a viewport is occluded in more than one place, you might have 
to execute the same deferred queue multiple times (that is, update the first 
region at one point and update the other region with the same operations 
later). To do so, define a region on the deferred queue when you redefine 
the first region in offscreen memory for deferred queue execution. This 
step informs the driver that the viewport still has an occluded region and 
prevents it from deleting the deferred queue. 


After the deferred queue drawing operations are executed to all the 
deferred regions of a viewport, use the Delete Deferred Queue Operation 
QIO to delete the drawing operations from the deferred queue. Also, when 
an application deletes a viewport with a region on the deferred queue, 
delete the deferred queue drawing operations for that region. 





Using Color 
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The QDSS driver uses several planes of memory to display color. 
Corresponding points in each plane of memory map to a single pixel on 
the display. The number of system-configured memory planes determines 
the depth or Z-mode of a pixel and the number of colors that can be 
simultaneously displayed. 


A driver configured with n planes of memory can display 2**n colors. 
The QDSS driver can be configured with four or eight planes of memory. 
Hence, a four-plane system can display 16 simultaneous colors and an 
eight-plane system can display 256. 


The total number of different colors a system can display is specified 

by a longword in the QDSS QVB block. The QDSS driver can define a 
maximum of 2**24 colors, but only 16 or 236 colors can be on the screen 
at any one time. 


Programming to the Driver 


Each displayable color is represented by a value in the hardware color map 
(the hardware look-up table). On color systems, a color is represented by 
one 16-bit intensity value for each primary color. On intensity systems, a 
color is represented by only one 16-bit value. The low-order eight bits of 
these values are ignored. The high-order eight bits represent the actual 
intensity values, which range from 0 to 255. 


2.19.1 Informing the Driver About Color 


Before an application can use the hardware color map, it must tell the 
driver which type of color system it is using. To identify a system as either 
color- or intensity-based, use the Set Color Characteristics QIO, specifying 
the second unique parameter as follows: 


e 0Q—Color system 


e 1—Intensity system 


Once the identification is complete, the driver accepts only Set Color Map 
Entries QIO requests that match this setting. The driver rejects all other Set 
Color Map Entries QIOs. 


2.19.2 Manipulating Color Map Values 


The values that represent pixels onscreen are used as indexes into the 
hardware color map. Pixel values are read in the Z-mode direction; for 
example, if only the first three planes of a pixel are used and the bits in the 
first and third planes are set, the resulting pixel value is 101 (binary). This 
value indexes into the fifth value in the hardware color map. Figure 2-11 
illustrates this. 
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Figure 2-11 
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Indexing the Hardware Color Map 
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If your application is not using the UIS environment, it must load any 
values it uses into the hardware color map with the Set Color Map Entries 
QIO, and specify the following information: 


e Index into the color map at which to begin initialization 
e Address of the buffer that contains the desired intensity values 


e Length of the buffer 


Call this QIO at any time to redefine the values in the color map. 


To determine the current values of the hardware color map, the application 
should use the Get Color Map Entries QIO and specify the following 
information: 


e Index into the color map at which to begin information retrieval 
e Address of the buffer that holds the returned intensity values 
e¢ Length of the buffer 
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QVSS/QDSS Common QlO Interface 


This chapter contains an alphabetical listing of descriptions of the QIO 
calls you can use with the QVSS and QDSS drivers. Table 3-1 organizes 
the QIOs in functional groups. 


Table 3-1 QIO Functional Groups 


Functional Group QiO Name 
: Enable Keyboard Input 
h 
Controlling the Keyboard Enable Keyboard Sound 
Modify Keyboard Characteristics 


Controlling Input { Enable Input Simulation \ 


Get Next Input Token 

Controlling the Pointer Define Pointer Cursor Pattern 
Enable Button Transition 
Enable Pointer Movement 

Controlling the Screen Initialize Screen ae 
Modify Systemwide Characteristics 
Enable Function Keys 


Controlling the Tablet { Enable Data Digitizing } 
Controlling User Entry Lists { Enable User Entry } 


Obtaining Information Get Keyboard Characteristics 
Get Number of List Entries 


Get System Information 
{ Load Compose Sequence Table } 
Revert to Default Compose Table 


Using Soft Keys { Load Keyboard Table } 
Revert to Default Keyboard Table 


Using Compose Keys 





How to Use This Chapter 


Before you call QIlOs, become familiar with Chapters 1 and 2 and 
Appendices A, B, and H. 


e¢ Chapters 1 and 2 describe the general operation of QIOs. 


e Appendices A and B contain pictures and descriptions of the data types 
you pass to the driver through the P1 to P6 parameters. 


e Appendix H describes the SYS$QIO system service. 


As you call QIOs, refer to the descriptions in this chapter. 


{ 


V4.1—June 1989 3~1 


QVSS/QDSS Common QIO Interface 


3.1.1 QIO Description Format 


3-2 


_ The QIO descriptions follow a strict format. The main headings in each 
QIO description and the type of information that appears there follow: 


QIO Name—Name of the QIO. 
Overview—Brief description of the operation the QIO performs. 


Format—Format of the call you must pass to SYS$QIO to perform the 
desired operation. 


Arguments in brackets are optional. Some programming languages, 
such as MACRO, allow you to omit optional arguments; the assembler 
supplies a default value of 0. Some other programming languages, 
such as FORTRAN, do not allow you to omit optional arguments; 

you must pass a value of 0 for any unspecified argument. Check the 
programming language documentation to see how the language handles 
optional arguments. 


Unique Parameters—Information that passes to the driver through 
$QIO P1 to P6 parameters; also indicates whether the parameter is 
required or optional. 


Description— Additional QIO operation information. 


Example—QIO example. 
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Define Pointer Cursor Pattern 


Define Pointer Cursor Pattern 


Defines the pointer cursor pattern for a given region on the physical 
screen. When the cursor enters that region, the new cursor pattern 
takes effect. Other arguments enable you to select the cursor style and 
reposition the pointer cursor. 





FORMAT SYS$QIO _[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,fastprm] ,p1 Lp2] LPS] [4] [pS] Lp6] 





UNIQUE P1 — IO$C_QV_SETCURSOR (required) 
PARAMETERS This function code identifies the action the QIO performs. 


To modify the QIO action, ““OR’”’ the IO$C_QV_SETCURSOR function 
code with one of the following optional function modifiers: 


Function Modifier Action 


1IO$M_QV_BIND Binds the pointer to the region specified in P6. 
Once the pointer enters the specified region, 
it cannot move outside the region’s borders. If 
the region becomes occluded, the pointer is no 
longer bound to the region. 


IO$M_QV_DELETE Deletes the specified pointer cursor pattern 
request. Any data contained in the type-ahead 
buffer is delivered to the specified AST address 
before the delete operation is executed. 


IO$M_QV_LAST Places the specified pointer cursor pattern 
request last in the entry list. If IOSM_QV_LAST 
is not specified, the request is placed first in 
the list. If an outstanding pointer cursor pattern 
request exists for the channel, it is updated to 
reflect the new entry. 


lIO$M_QV_LOAD_DEFAULT Makes the specified cursor pointer the system 
default cursor pointer. If you specify this function 
modifier, the system ignores any screen region 
you specify in P6. 


IO$M_QV_USE_DEFAULT Requests that the system use the system default 
cursor pointer when the region specified in P6 
becomes active. !f you specify this function 
modifier, the system ignores any arguments you 
specify in P2, P4, and P5. 


lO$M_QV_TWO_PLANE_ Indicates the system is loading a multiplane 

CURSOR cursor pattern. Use this modifier to load a 
cursor pattern on a QDSS system. Refer to 
the Description section for more information on 
multiplane cursors. 
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P2—Bitmap image address (optional) 

This parameter is either a 16-word array or, on multiplane cursor systems, 
a 32-word array. The QVB contains a field that informs you whether yours 
is a single-plane or multiplane system. Use the Get System Information 
QIO to access this field. (See Description section.) 


P3—New cursor position address 

This parameter is a longword that points to a two-longword array that 
defines the new cursor position: the first specifies the X coordinate of the 
new cursor position in pixels; the second specifies the Y coordinate of the 
new cursor position in pixels. 


If P3 is 0, the pointer cursor is not repositioned. 


The following diagram shows the data structure that defines the new cursor 
position. 










X position on physical screen 0 
Y position on physical screen 4 


Field Use 
X position on physical screen Specifies X coordinate in pixels 
Y position on physical screen Specifies Y coordinate in pixels 


P4—Pointer cursor hot spot definition address 
This parameter is an address that points to a two-longword array that 
defines the pointer cursor hot spot, the point within the 16- x 16-pixel 
cursor display region that is the actual cursor position. The following 
diagram shows the data structure that defines the cursor hot spot. 


: 
Y offset 4 | 





Field Use 


X offset The X offset in pixels from the upper left corner of the pointer pattern 
to the active point. 


Y offset The Y offset in pixels from the upper left corner of the pointer pattern 
to the active point. 
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P5—Cursor style definition value 


This parameter is a longword value in the range 0 through 3 that defines 
how the cursor is presented against the background screen. 


This parameter is ignored for multiplane cursor systems. 


The following table lists each value and the style it denotes. 


Value‘ Style 


0 Dynamic NAND. The background under the cursor hot spot is examined. 
If it is black (all off), the cursor is NANDed with the background: If the 
background is not black, the cursor is ORed with the background. 


1 Dynamic OR. The background under the cursor hot spot is examined. 
If it is black (all off), the cursor is ORed with the background. If the 
background is not black, the cursor is NANDed with the background. 


NAND. The cursor is always NANDed with the background screen. 
OR. The cursor is always ORed with the background screen. 


P6—Screen rectangle values block address 
(optional) 


This parameter is a longword that points to a screen rectangle values block 
that defines a rectangle on the screen. If you do not specify P6, a default 
rectangle that covers the entire screen is used. 


The following diagram shows the data structure that defines the screen 
rectangle. 










ee 
oe 
ee 
wr rian 


Field Use 

MINX (left side value) Pixel value for left side of rectangle 
MINY (bottom side value) Pixel value for bottom side of rectangle 
MAXX (right side value) Pixel value for right side of rectangle 
MAXY (top side value) Pixel value for top side of rectangle 





DESCRIPTION Wher the pointer cursor moves outside a currently active rectangle, a 
special signal notifies the process that the cursor has left the region. 
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The QVSS and QDSS drivers allow you to specify a pointer cursor pattern 
that defines the shape of the cursor (QDSS systems use a multiplane cursor 
that is described in the following section). The shape can be in the form 
of a block, a cross, an arrow, or any other configuration. You can also 
define the cursor style (how the cursor is presented against the background 
screen) and the location of the cursor hot spot (the point within the cursor 
pattern region that is the actual cursor position). In addition to moving the 
cursor with the pointer, you can also reposition the cursor by specifying 
new X and Y cursor coordinates. 


Multiplane Cursor Patterns 


If your system uses a multiplane cursor (QDSS), you can specify a 32- 
word arttay as a cursor pattern. Currently, multiplane cursors consist of 
two planes. Typically, you use two planes to prevent the cursor from 
disappearing when it is moved over varying backgrounds. To understand 
how the two planes work, think of the 32-word array as two 16-word arrays, 
array A and array B. 


The bit pattern in array A is determined as follows: 
¢ 1—Indicates that the corresponding pixel must be filled. 


¢ 0Q—Indicates that whatever is on the screen at the corresponding pixel 
should show through (remember, the cursor is overlaid on the screen). 


The bit pattern in array B uses the the bits set to 0 in array A as a mask; 
those corresponding bits are ignored in array B. The remaining bit pattern 
in array B is determined as follows: 


¢ 1—Indicates that the corresponding pixel must be filled with the 
background color. 


e 0—lIndicates that the corresponding pixel must be filled with the 
foreground color. 





EXAMPLE 


The following example shows the typical assignment of a pointer cursor 
region. 
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QVSCURSOR1: 


REGION1: 


20$ 


30$ 


- WORD 
- WORD 
- WORD 
«WORD 
-» WORD 
-WORD 
» WORD 
- WORD 
«WORD 
«WORD 
.» WORD 
» WORD 
- WORD 
«WORD 
«WORD 
«WORD 


- LONG 
+ LONG 
.» LONG 
» LONG 


MOVL 
SQIOW_S 


BLBS 
BRW 


MOVL 
$QIOW_S 


BLBS 
BRW 


4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
461111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
461111111111111111 
4b1111111111111111 
4b1111111111111111 
461111111111111111 
461111111111111111 
4b1111111111111111 
*b61111111111111111 
461111111111111111 


20 


300 
300 


#10$C_QV_SETCURSOR, RO 


CHAN=CUR_CHAN1,- 


FUNC=#10$_SETMODE, - 


Pl =(RO),- 
P2=#QVSCURSORL, - 
P6=#REGION1 

RO, 30$ 

ERROR 


#IOSC_QV_SETCURSOR, RO 


CHAN=CUR_CHAN2,- 


FUNC=#10$_SETMODE, - 


P1=(RO),- 
P2=#QV$CURSOR2, - 
P6=#REGION2 
RO,40$ 

ERROR 


QVSS/QDSS Common QIO Interface 


; INITIAL 16 X 16 
; PATTERN 


; CURSOR REGION 1 


DEFINE CURSOR 1 
ASSIGNED CHANNEL 
SET MODE QIO 


CURSOR DESCRIPTI 
CURSOR REGION 
NO ERROR IF SET 


se se se Ne Ne Ne Ne 


DEFINE CURSOR 2 
SECOND ASSIGNED 


we se 


NO ERROR IF SET 


~e 
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CURSOR 


CURSOR PATTERN REQUEST 


ON 


CHANNEL 
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Enable Button Transition 


Enable Button Transition 


Enables repeating pointer button ASTs for the process on the specified 
channel. If this request has the highest priority for the specified rectangle, 
each button transition delivers an AST when the pointer cursor enters that 
area of the physical screen. 





FORMAT SYSSQIO = [efn] ,chan ,JO$_SETMODE , [iosb] ,[astadr] 
,[astorm] ,p1 ,p2 [,p3] 4] L p5] L, p6] 





UNIQUE P1—IO$C_QV_ENABUTTON (required) 


PARAMETERS _slhis function code identifies the action the QIO performs. This parameter 
must be specified. 


To modify the QIO action, ‘‘OR” the IO$C_QV_ENABUTTON function 
code with one of the following optional function modifiers: 


Function Modifier Action 


1O$M_QV_DELETE Deletes the specified pointer button request. Any 
data in the type-ahead buffer is delivered to the 
specified AST address before the delete operation is 
executed. 


IOSM_QV_LAST Places the specified pointer button request last in the 
list. If lOSM_QV_LAST is not specified, the request is 
placed first in the list. If an outstanding pointer button 
request exists for the channel, it is updated to reflect 
the new priority. 


IO$¢M_QV_PURG_TAH Purges the type-ahead buffer of any existing pointer 
button transitions. 


P2—Pointer button AST specification block address 
(required) 


This parameter is a longword that points to a pointer AST specification 
block that specifies a user-supplied AST routine that is notified each time a 
pointer button transition occurs. 


The following diagram shows the data structure that specifies a pointer 
button AST. 


AST service routine address 0 
AST parameter 4 


access mode 8 
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input token address 12 


Field Use 
AST service routine address AST service routine address is 0 if no AST 


routine is required. If no AST routine is 
specified, input is stored in the type-ahead 
buffer and delivered either when an AST 
region is declared or when a Get Next Input 
Token QIO is issued. The type-ahead buffer 
holds 32 input tokens or characters. 


AST parameter The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

Access mode The access mode where the AST is delivered 


is maximized with the current access mode. 


Input token address The address of a longword that receives an 
input token when an AST routine is called. 
Word 0 of the longword receives token or 
character data. The token is a decimal value 
that indicates which button is activated. The 
values are assigned to the pointer buttons 
sequentially, starting with the select button, 
which is always 400. The driver stores the 
token in the low-order word of the longword. 


Bit 15 of the high-order word determines 
whether the transition is up (0) or down 

(1). The remainder of the high-order word 
contains control information you can use 

to determine if the [Shift] (bit 12), [Ctrl] (bit 
13), or (bit 14) keys are pressed. You 
can use these as meta-keys (keys used in 
combination). When the bit is set, the key is 
down. 


P3—Must be 0 


P4—Pointer button characteristics block address 
(optional) 


This parameter is a longword that points to a pointer button characteristics 
block. This block specifies which button-related characteristics to enable 
or disable for the button region. When the region becomes active, the 
specified characteristics become active. 


The following diagram shows the data structure that specifies pointer 
button characteristics. 
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enabled characteristics mask 





0 
a 
a 
a a 


Field Use 
Enabled characteristics Longword of characteristics to be enabled. 
mask 


Disabled characteristics Longword of characteristics to be disabled. 


mask The pointer button characteristics, defined by the 


$QVBDEF macro, consist of the following bit: 





Characteristic Meaning 


QV$M_BUT_ After a pointer button down transition 

UPTODOWN occurs, the current pointer button 
request receives all future pointer 
button transitions until all pointer 
buttons return to the up position 
(regardless of the position of the 
pointer cursor on the physical screen). 
if this characteristic is disabled, 
then each up and down transition is 
delivered to whichever button request 
is active for the current pointer cursor 
position. Default is on. 


0 This longword must be zero. 
This longword must be zero. 


P5—Must be 0 


P6—Screen rectangle values block address 
(optional) | 


This parameter is a longword that points to a screen rectangle values block. 
This block defines the area on the physical screen for which the specified 
button transition is enabled. 


If you do not specify a screen rectangle values block, a default rectangle 
that covers the entire screen is used. 


The following diagram shows the data structure that defines the screen 
rectangle. 
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ec 
a 
ee 
eS 


Field Use 

MINX (left side value) Pixel value for left side of rectangle 
MINY (bottom side value) Pixel value for bottom side of rectangle 
MAXX (right side value) Pixel value for right side of rectangle 
MAXY (top side value) Pixel value for top side of rectangle 





DESCRIPTION = The QOVSS and QDSS drivers support a multibutton pointer. A process 
enables a pointer button request to indicate a pointer button transition, either 
up or down. A token passes to the specified AST routine to signal which 
button made a transition and the type of transition (up or down). Many 
applications are interested only in pointer button events that occur in 
a specific region of the physical screen. The P6 parameter specifies a 
rectangle on the physical screen that defines the area where the application 
is interested in pointer button transitions. If rectangles for pointer button 
requests for multiple channels (or processes) overlap, the first rectangle on 
the list gets priority. 
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EXAMPLE 


SET_BUTTONAST: 


SASSIGN_ 


BLBS 

BRW 
10S: MOVL 

$QIOW_S 


BLBS 

BRW 
208: RSB 
BUT_BLOCK: 


- LONG 
» LONG 
- LONG 
«LONG 


BUT_REGION: 
. LONG 
. LONG 
. LONG 
. LONG 
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The following example shows typical programming and use of pointer 


button ASTs. 


iS) DEVNAM=WS_DEVNAM, - 
CHAN=BUT_CHAN 


RO,10$ 

ERROR 
#IO$C_QV_ENABUTTON, RO 
CHAN=BUT_CHAN, - 
FUNC=#10$_SETMODE, - 
P1=(RO),- 
P2=#BUT_BLOCK, - 
P6=#BUT_REGION 
RO,20$ 

ERROR 


se Ne se we 


~e 


BUT_AST 
0 

0 
BUTTON 


Ne we Ne Ne Se Se Ne 


~e 


20 


300 
300 


+ ASSIGN CHANNEL USING 
LOGICAL NAME AND 
CHANNEL NUMBER 

NO ERROR IF SET 

ERROR 


NO ERROR IF SET 


BUTTON AST 
SPECIFICATION BLOCK 
AST ADDRESS 

AST PARAMETER 
ACCESS MODE 

BUTTON INFORMATION 
LONGWORD 


AST REGION 
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Enable Data Digitizing 


If the system pointing device is a tablet, the Enable Data Digitizing QIO 
enables you to use the tablet as a data digitizer. 





FORMAT SYS$QIO_ [efn] ,chan ,IO$_SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 [,p4] ,p5 [, 6] 





UNIQUE P1—IO$C_QV_ENABLE_DIGITIZING (required) 
PARAMETERS This function code identifies the action the QIO performs. 


To modify the QIO action, ““OR’’ the IO$C_QV_ENABLE_DIGITIZING 
function code with the following optional function modifier: 


Function Modifier Action 


IO$M_QV_DELETE Deletes the specified data digitizing request. Any data in the 
, type-ahead buffer is delivered to the specified AST address 
before the delete operation is executed. 


P2—Pointer movement AST specification block 
address (optional) 


This parameter is a longword that points to a pointer movement AST 
specification block that specifies a user-supplied AST routine. The routine 
is notified when pointer movement occurs inside the data rectangle 
specified in P6. The pointer position is reported using the best granularity 
in which the device can report. 


The following diagram shows the data structure that specifies a pointer 
movement AST for the tablet. 
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Field Use 


AST service routine address The AST service routine address is 0 if no 
AST routine is required. No buffering of data 
in the type-ahead buffer occurs for pointer 


motion ASTs. 

AST parameter The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

Access mode The access mode where the AST is delivered 


_ is maximized with the current access mode. 


New pointer cursor position address The fourth longword contains the address 
of a longword that receives the new pointer 

cursor position when the AST routine is 
called. (If your application does not need 
this information, specify a 0.) The low-order 
word receives the new X pixel location of the 
pointer cursor; range of X is defined in the 
qvb$w_tablet_width field of the QVB block. 
The high-order word receives the new Y pixel 
location of the cursor; range of Y is defined 
in the qvb$w_tablet_height field of the QVB 
block. © 


P3—Pointer button AST specification block address 
(optional) 


This parameter is a longword that points to a pointer button AST 
specification block. This block specifies a user-supplied AST that is 
notified when a button transition occurs. 


The following diagram shows the data structure that specifies the pointer 
button AST for the tablet. 











ee 
a 
a 
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Field Use 


AST service routine address The AST service routine address is 0 if no 
AST routine is required. If no AST routine is 
specified, input is stored in the type-ahead 
buffer and delivered either when an AST 
region is declared or when a Get Next Input 
Token QIO is issued. The type-ahead buffer 
holds 32 input tokens or characters. 


AST parameter The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

Access mode The access mode where the AST is delivered 
is maximized with the current access mode. 

Input token address This is the address of a longword that 


receives an input token when an AST routine 
is called. Word 0 of the longword receives 
token or character data. The token is a 
decimal value indicating which button was 
activated. The values are assigned to the 
pointer buttons sequentially starting with 

the select button, which is always 400. The 
driver stores the token in the low-order word 
of the longword. Bit 15 of the high-order word 
determines whether the transition is up (0) or 
down (1). 


The rest of the high-order word contains 
more control information that can be used to 


determine if the (bit 14), (bit 13), 
or [Lock] (bit 12) keys are pressed. You can 
use these keys as meta-keys (keys used in 
combination). When the bit is set, the key is 
down. 


P4, P5—Must be 0 


P6—Data rectangle values block address 
(optional) 


This parameter is a longword that points to a data rectangle values block 
that defines the active rectangle on the tablet. The origin (0,0) of the tablet 
is the lower left-hand corner. 


If you do not specify a data rectangle values block, a default rectangle that 
covers the entire tablet is used. 


The following diagram shows the data structure that defines a data 
rectangle. 
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MINY (bottom side value) 


4 
MAXX (right side value) 8 
MAXY (top side value) 12 


Field Use 

MINX (left side value) Pixel value for left side of rectangle 
MINY (bottom side value) Pixel value for bottom side of rectangle 
MAXX (right side value) Pixel value for right side of rectangle 
MAXY (top side value) Pixel value for top side of rectangle 


a a a a a a a a a a a a PR A a aT NE AEE 

DESCRIPTION Only the process that issues the data digitizing request can change or 
cancel it. When the process is deleted, any outstanding data digitizing is 
canceled. 


Only one data digitizing region can be active at a time. When one process 
has declared a data digitizing region, attempts by other processes to declare 
an additional data digitizing region fail. 
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Enable Function Keys 


Enables the windowing system to access function keys F1 through F5, 
which are reserved for workstation control functions and should not be 
used in application programs. These keys are defined by the driver, which, 
in addition to informing the owner of the key of the keypress, performs 
special functions. 








FORMAT SYS$QIO__[efn] ,chan ,[O$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p7 ,p2 ,p3 [,p4] [,P5] [, PE] 

UNIQUE P1—IO$C_QV_ENAFNKEY (required) 

PARAMETERS _Phis function code identifies the action the QIO performs. 








P2—Reserved function keystroke AST specification 
block address (required) 


This parameter is a longword that points to a reserved function keystroke 
AST specification block. This block specifies a user-supplied AST routine 
that is notified each time a keystroke occurs. 


The following diagram shows the data structure that specifies a reserved 
function keystroke AST. 






Field Use 


AST service routine address Specify 0 if no AST routine is required. If no 
: AST routine is specified, input is stored in 
the type-ahead buffer and delivered either 
when an AST region is declared or when a 
Get Next Input Token QIO is issued. The 
type-ahead buffer holds 32 input tokens or 
characters. 


AST parameter The user-defined AST parameter delivered 
to the AST routine. The driver does not 
examine it. 
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Field 


Access mode 


Input token address 


Use 


This is the access mode where the AST is 
delivered. It is maximized with the current 
access mode. 


This is the address of a longword that 
receives an input token when an AST routine 
is called; word 0 of the longword contains 
token data defined by the $SMGDEF macro 
for these function keys. By default, an AST is 
signaled only on a down transition. 


P3—Symbolic name for function key to associate 
with request 


This parameter is a symbolic name that indicates the function key to 
associate with this request. The following bits are defined: 


Key Value 


QV$M_KEY_F1 
QV$M_KEY_F2 


QV$M_KEY_F3 


QVS$M_KEY_F4 
QV$M_KEY_F5 


Function 


Driver signals AST and toggles keyboard Hold Screen lamp. 


Operator screen. If the SYSGEN parameter WS_OPADO is set 
to 1, toggles between the workstation screen and the operator 
screen. 


Switch window. If an alternate windowing system is enabled, 
the driver signals an AST and toggles between the windowing 
systems. (This value applies to monochrome VAXstation | and Il 
workstations.) 


The driver signals an AST. 
The driver signals an AST. 


P4, P5, P6—Must be 0 





EXAMPLE 


108: MOVL 


BLBS. 
BRW 


The following example shows typical programming for the F5 function key. 


#1O0$C_QV_ENAFNKEY, RO 
$QIOW_S CHAN=FNKEY_F5_CHAN, - 
FUNC=#10$_SETMODE, - 
P1=(RO),- 
P2=#FNKEY_BLOCK, - 
P3=#QVSM_KEY_F5 


RO, 308 
ERROR 


me we Ne Ne Ne Ne Ne 


FUNC KEY REQUEST TO RO 
ASSIGNED CHANNEL 
SET MODE QIO 


; FUNCTION KEY REQUEST 


AST SPEC BLOCK 


; NO ERROR IF SET 
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FUNCTION KEY AST 
SPECIFICATION BLOCK 
AST ADDRESS 

AST PARAMETER 
ACCESS MODE 

INPUT TOKEN STORAGE 


FNKEY_BLOCK: 


.LONG F5_AST 
-LONG F5_ACK 
-LONG 0 

.LONG CHARACTER 


se we Ne Ne Ne we 
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Enable Input Simulation 


Simulates keystrokes, pointer motion, and pointer button transitions. 





FORMAT SYS$QIO__[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astorr] ,p1 [,p2] [, 3] [,P4] [,P5] [, p6] 





UNIQUE P1—lIO$C_QV_SIMULATE (required) 
This function code identifies what action the QIO performs. If you set the 
PARAMETERS TYPE field in the string descriptor you use to TYPE_T2 (value 38), the string 
is evaluated as 16-bit characters rather than 8-bit characters, and any 16-bit 
value can be passed as the low word for keyboard input. 


NOTE: The LENGTH field in the descriptor is the number of 16-bit characters. 
rather than a byte-count. 


P2—ASCIl text descriptor address (optional) 

This parameter is a longword that points to a descriptor for the ASCII 
text to send to the current keyboard region. The maximum number of 
characters allowed in the text string is 32. If P2 is 0, no data is sent. 


P3—New pointer position address (optional) 

This parameter is a longword that points to a two-longword array that 
defines a new pointer position: the first specifies the X coordinate of the 
new pointer position in pixels; the second specifies the Y coordinate. 


If P3 is 0, the pointer is not repositioned. 


The following diagram shows the data structure that specifies the new 
pointer position. 





X position on physical screen 0 
Y position on physical screen 4 


Field Use 
X position on the physical screen Specifies X coordinate in pixels 
Y position on the physical screen Specifies Y coordinate in pixels 


P4—Button simulation block address (optional) 
This parameter is a longword that points to a button simulation block that 
specifies which pointer buttons are pressed or released. 


If P4 is 0, the pointer buttons are not modified. 


The following diagram shows a button simulation block. 
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Field 


Buttons to be pressed mask 
Buttons to be released mask 


P5, P6—Must be 0 


V4.1—June 1989 


buttons to be pressed mask 
buttons to be released mask 


Enable Input Simulation 






Use 


Mask of the buttons to be pressed 
Mask of the buttons to be released 


Pointer button definitions used in the masks 
defined by the $QVBDEF macro, consisting of 
the following symbols: 


Symbol Meaning 


QV$M_BUTTON_1 Select button 
QV$M_BUTTON_2 Button 2 
QV$M_BUTTON_3 Button 3 
QV$M_BUTTON_4 Button 4 


This longword must be zero. 
This longword must be zero. 
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EXAMPLE The following example shows typical programming for input simulation. 


5$3 BSBW SET_CHARACTERISTICS SET UP SYSTEM 
CHARACTERISTICS 
SET UP NEW SYSTEMWIDE 


BSBW SET_PERM_CURSOR 
CURSOR PATTERN 


~e we Ne Ne 


. BSBW SET_MOUSEAST 
BSBW SIMULATE_INPUT 


SET UP MOUSE REGION AST 
SIMULATE INPUT ON 
KEYBOARD 2. 

CLEAR EVENT FLAG #2 

WAIT FOR EVENT FLAG #2 


SCLREF_S EFN=#2 
$WAITFR_S EFN=#2 


we se we Ne Ne 


ERROR: $EXIT_S RO 


SIMULATE_INPUT: 


MOVL #IOSC_QV_SIMULATE, RO : SIMULATE KEYBOARD INPUT 
$QIOW_S CHAN=KBD_CHAN2,- * ON KEYBOARD CHANNEL 2 
FUNC=#10$_SETMODE,- 
P1=(RO),- 
P2=#SIM_ACK,- 
P3=#0 
BLBS RO,20$ + NO ERROR IF SET 
BRW ERROR , 
2083 RSB 


SIM_ACK: 
-ASCID /This input SIMULATED on chan 2./ 
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Enable Keyboard Input 


Enables repeating character input ASTs for the process on the specified 








channel. 
FORMAT SYS$QIO_[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,07 ,p2 ,[p3] ,[P4] [05] [, 6] 
UNIQUE P1—IO$C_QV_ENAKB (required) 


PARAMETERS his function code identifies the action the QIO performs. 


To modify the QIO action, ‘““OR’’ the IO$C_QV_ENAKB function code with 
one of the following optional function modifiers: 


Function Modifier Action 


IO$SM_QV_CYCLE Removes the active keyboard from the top of the 
keyboard request list and places it at the end of the 
list (lowest priority). The next highest priority keyboard 
request then becomes the active keyboard request and 
a contro! AST is delivered on its behalf. 


1O$M_QV_DELETE Deletes the specified keyboard request. Any data 
contained in the type-ahead buffer is delivered to the 
specified AST address before the delete operation is 
executed. 


IOSM_QV_LAST Places the specified keyboard request last in the list. If 
IO$M_QV_LAST is not specified, the request is placed 
first in the list. If an outstanding keyboard request 
exists for the channel, it is updated to reflect the new 
priority. . 
h)$M_QV_PURG_TAH Purges the type-ahead buffer of any keyboard request 
on this channel. 


P2—Keystroke AST specification block address 


(required) | 

This parameter is a longword address that points to a keystroke AST 
specification block. This block specifies a user-supplied AST routine that is 
notified each time a keystroke occurs. 


The following diagram shows the data structure that specifies a keystroke 
AST. 





AST service routine address 0 
AST parameter 4 
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input token address 






12 


Field Use 


AST service routine address The AST service routine address is 0 if no 
AST routine is required. If no AST routine is 
specified, input is stored in the type-ahead 
buffer and delivered either when an AST region 
is declared or when a Get Next Input Token QIO 
is issued. 


AST parameter The user-defined AST parameter is delivered to 
the AST routine. The driver does not examine it. 


Access mode The access mode where the AST is delivered is 
maximized with the current access mode. 


“Input token address This value is the address of a longword that 


receives an input token when an AST routine 
is called. Word 0 of the longword contains 
token or character data. Values from 0 to 255 
map into the Digital multinational character set. 
Values from 256 to 512 map function keys into 
token values. Word 1 of the longword contains 
control information; bit 15 defines the status 
of a token (1 equals down, 0 equals up). By 
default, an AST is only signaled on a down 
transition. 


The rest of the high-order word contains 
more control information that can be used to 
determine if the (bit 12), [Ctrl] (bit 13), 
or (bit 14) keys are pressed. You can 
use these keys as meta-keys (keys used in 
combination). When the bit is set, the key is 
down. 


P3—Keyboard request AST specification block 
address (optional) 


This parameter is a longword address that points to a keyboard request 
AST specification block. This block specifies a control AST routine that 
is notified when a keyboard request becomes active. A keyboard request 
becomes active when the active keyboard owner is deleted or a cycle 
request causes it to become active. No control AST is delivered when 
the new request is already active or the owning process issued the cycle 
request. 


The following diagram shows the data structure that specifies a keyboard 
request AST. 
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Field Use 


AST service routine address The address of the AST service routine is 0 if 
no AST routine is required. If no AST routine 
is specified, input is stored in the type-ahead 
buffer and delivered either when an AST region 
is declared or when a Get Next Input Token QIO 
is issued. The type-ahead buffer holds 32 input 
tokens or characters. 


AST parameter The user-defined AST parameter is delivered to 
the AST routine. The driver does not examine it. 

Access mode The access mode where the AST is delivered is 
maximized with the current access mode. 


0 The fourth longword must be zero. 


P4—Keyboard characteristics block address 
(optional) 


This parameter is a longword address that points to a keyboard 
characteristics block that describes keyboard-related characteristics to be 
enabled or disabled for the keyboard region. The specified characteristics 
are enabled or disabled when the keyboard region becomes active. 


The keyboard characteristics block is ignored if the keyboard region for 
this channel already exists. To modify the characteristics of an existing 
keyboard region, use the Modify Keyboard Characteristics QIO. 


The default characteristics are specified in the systemwide characteristics 
block, which can be modified using the Modify Systemwide Characteristics 
QIO. The current systemwide characteristics are stored in the 
characteristics field of the QVB. 


The following diagram shows the data structure that specifies the keyboard 
characteristics block. 


enabled characteristics mask 
disabled characteristics mask 


keyclick volume 
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Field Use 





Enabled The first longword is a mask of characteristics to be 
characteristics mask enabled. 


Disabled The second longword is a mask of characteristics to be 
characteristics mask. _—_ disabled. 


The keyboard characteristics, defined by the $QVBDEF 
macro, consist of the following bits: 


Characteristic Default Meaning 

QV$M_KEY_ On Key held down 
AUTORPT automatically repeats. 
QV$M_KEY_ On Keyclick sounds on each 
KEYCLICK keystroke. 
QV$M_KEY_UDF6 Off Function keys F6 


through F10 generate 
up/down transitions. 


QV$M_KEY_UDF11 Off Function keys F11 
through F14 generate 
up/down transitions. 


QV$M_KEY_UDF17 Off Function keys F17 
through F20 generate 
up/down transitions. 


QV$M_KEY_ Off Function keys HELP and 

UDHELPDO DO generate up/down 
transitions. 

QV$M_KEY_UDE1 Off Function keys E1 


through E6 generate 
up/down transitions. 


QV$M_KEY_ Off Arrow keys generate 
UDARROW up/down transitions. 
QV$M_KEY_ Off Numeric keypad keys 
UDNUMKEY . generate up/down 
transitions. 
Keyclick volume The keyclick volume is a value from 1 (loudest) to 8 


(softest). If a value of 0 is specified, the current system 
default keyclick volume is used. 


0 The fourth longword must be 0. 


P5, P6—Must be 0 





EXAMPLE The following example shows a typical assignment of two terminal 
channels, keyboard requests on those channels, and associated AST 
routines. 
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P2_BLOCK1: 
. LONG 
. LONG 
. LONG 
. LONG 


ACK1: -ASCID 


P2_BLOCK2: 
. LONG 
. LONG 
. LONG 
. LONG 


ACK2: ~ASCID 


P3_BLOCK: 


-« LONG 
- LONG 
- LONG 
- LONG 


SET_KBDAST: 


SASSIGN_S DEVNAM=WS_DEVNAM, ~ 


BLBS 
BRW 


20$: MOVL 


KBD_AST 
ACK1 

0 
CHARACTER 


~e se we se 


° 
‘ 
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AST SPECIFICATION BLOCK 1 


AST ADDRESS 

AST PARAMETER 
AST DELIVERY MODE 
INPUT TOKEN 


/INPUT ACKNOWLEDGED CHANNEL 1/ 


KBD_AST 
ACK2 

0 
CHARACTER 


e 
, 


AST SPECIFICATION BLOCK 2 


/INPUT ACKNOWLEDGED CHANNEL 2/ 


CTL_AST 
0 
0 
0 


CHAN=KBD_CHAN2 


RO,5$ 
ERROR 


#I0SC_QV_ENAKB, RO 


$QIOW_S CHAN=KBD_CHANZ, - 


BLBS 
BRW 


FUNC=#10$_SETMODE, - 
P1=(RO),- 
P2=#P2_BLOCK2,- 
P3=#P3_BLOCK 

RO,30$ 

ERROR 
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~e se we Se Ne NO 


~e se NO we 


~e se se Ne Ne we Ne NO 


CONTROL AST SPECIFICATION 


BLOCK 

CONTROL AST ADDRESS 
AST PARAMETER 

AST DELIVERY MODE 
MUST BE ZERO 


; ASSIGN CHANNEL USING 
LOGICAL NAME AND 
CHANNEL NUMBER 

NO ERROR IF SET 

ERROR 


ENABLE KEYBOARD AST 
REQUEST TO RO 
ASSIGNED CHANNEL 

SET MODE QIO 
KEYBOARD AST REQUEST 
USER AST ROUTINE 
CONTROL AST ROUTINE 
NO ERROR IF SET 


Enable Keyboard Input 
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KBD_AST: 
F5_AST: 
- WORD 
PUSHL 
CALLS 
BLBS 
5$: BRW 


10$: CMPW 
BNEQ 
BSBW 
BRB 


208: PUSHAL 
CALLS 
BLBC 


CMPB 
BNEQ 
BSBW 
BRB 


308: CMPB 
BNEQ 


4(AP) 
#1,G*LIBS$PUT_LINE 
RO, 10$ 

ERROR 


#KEY$C_F5, CHARACTER 
20$ 

CYCLE_KBD 

40$ 


DESC 
#1,G*LIBSPUT_LINE 
RO,5$ 


#°A/C/,CHARACTER 
30$ 

CYCLE_KBD 

40$ 


#4A/F/,CHARACTER 
40S 


S$SETEF_S EFN=#2 


40S: RET 


CTL_AST: 
» WORD 
PUSHAL 
CALLS 
BLBS 
5S: BRW 


1083: RET 
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CYCLE 
#1,G*°LIBSPUT_LINE 
RO, 105 

ERROR 


se Ne 


we Ne 


=e ~e ne 


~e 


SEND ACKNOWLEDGMENT 
MESSAGE 


WAS F5 TYPED? 


CYCLE THE KEYBOARD LIST 
AND EXIT 


SEND CHARACTER TYPED 


WAS A "C" TYPED? 


CYCLE THE KEYBOARD LIST 


WAS AN "F" TYPED? 


YES, EXIT PROGRAM 


SEND ACKNOWLEDGMENT 
MESSAGE 


V4.1—June 1989 


QVSS/QDSS Common QIO Interface 
Enable Keyboard Sound 


Enable Keyboard Sound 


Enables a process to make a bell or keyclick sound on the LK201 
keyboard: 








FORMAT SYSS$QIO_[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,pT ,p2 [,p3] [,p4] [, p5] [,p6] 

UNIQUE P1—IO$C_QV_SOUND (required) 

PARAMETERS _ This function code identifies the action the QIO performs. 


P2—Symbolic name that denotes type of sound 
(required) 


This parameter is a symbolic name that denotes the type of sound. The 
sound types, defined by the $QVBDEF macro, consist of the following bits: 


Characteristic Meaning 


QV$M_SOUND_BELL Sound bell. 
QV$M_SOUND_CLICK Sound keyclick. 


P3—Value that specifies the sound volume 
(optional) 


This parameter specifies the sound volume, a value from 1 (loudest) to 
8 (softest). If a value of 0 is indicated, the previously specified (that is, 
current) volume is used. 


P4, P5, P6é—Must be 0 
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EXAMPLE 


2083 


3-30 


MOVL §§ #I0$C_QV_SOUND, RO 

$QIOW_S CHAN=SYS_CHAN1,- 
FUNC=#10$_SETMODE, - 
Pl = (RO),- 
P2=#QV$M_SOUND_BELL 

BLBS RO, 208 

BRW ERROR 


=e Ne Ne Ne NO NO 


The following example shows how the bell sound can be programmed. 


SOUND REQUEST TO RO 
ASSIGNED CHANNEL 
SET MODE QIO 

SOUND REQUEST 

SOUND TYPE IS BELL 
NO ERROR IF SET 
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Enable Pointer Movement 


Enables repeating pointer motion ASTs for the process on the specified 
channel. If this request has the highest priority for the specified rectangle, 
each pointer motion delivers an AST when the pointer cursor enters the 
specified area of the physical screen. 








FORMAT SYSSQIO_[efn] ,chan ,IO$_SETMODE , [iosb] , [astadr] 
,[astprm] ,p1 ,p2 ,[p3] ,[p4] [,P5] [, 6] 

UNIQUE P1—IO$C_QV_MOUSEMOV (required) 

PARAMETERS _Lhis function code identifies the action the QIO performs. 


To modify the QIO action, “OR” the IO$C_QV_MOUSEMOV function 
code with one of the following optional function modifiers: 


Function Modifier Action 


IO$M_QV_DELETE Deletes the specified pointer motion request. Any data 
contained in the type-ahead buffer is delivered to the 
specified AST address before the delete operation is 
executed. 


lO$M_QV_LAST Places the specified pointer motion request last in the list. If 
IO$M_QV_LAST is not specified, the request is placed first in 
the list. If an outstanding pointer motion request exists for 
the channel, it is updated to reflect the new priority. 


P2—Pointer motion AST specification block address 
(required) | 


This parameter is a longword that points to a pointer motion AST 
specification block. This block specifies a user-supplied AST routine that is 
notified when pointer motion occurs. 


The following diagram shows the data structure that specifies a pointer 
motion AST. 


: AST service routine address 
AST parameter 


address of new pointer cursor position 
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Field Use 


AST service routine address The AST service routine address is 0 if no 
AST routine is required. No buffering of data 
in the type-ahead buffer occurs for pointer 


motion ASTs. 

AST parameter The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. | 

Access mode The access mode where the AST is delivered 


is maximized with the current access mode. 


New pointer cursor position address The fourth longword contains the address 
of a longword to receive the new pointer 
cursor position when the AST routine is 
called. (If your application does not need 
this information, specify 0.) The low-order 
word receives the new X pixel location of the 
pointer cursor; the high-order word receives 
the new Y pixel location of the cursor. For 
screen pointers, X is from 0 through 1023, 
with the lowest value denoting the left side 
of the screen; Y is from range 0 through 863 
with the lowest value denoting the bottom of 
the screen. For tablet pointers, the range of 
X is defined in the qvb$w_tablet_width field 
of the QVSS block; the range of Y is defined 
in the qvb$w_tabiet_height field of the QVB 
block. 


P3—Pointer cursor exit AST specification block 
address (optional) 

This parameter is a longword that points to a pointer cursor exit AST 
specification block. This block specifies a user-supplied control AST 


routine that is notified when the pointer cursor exits from the rectangle 
specified by P6. 


The following diagram shows the data structure that specifies a pointer 
cursor exit AST. 


AST service routine address 











0 
str dA 
en 
ee 
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Field Use 

AST service routine address The AST service routine address is 0 if no 
AST routine is required. 

AST parameter The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

Access mode The access mode where the AST is delivered 
is maximized with the current access mode. 

0 The fourth longword must be zero. 

P4, P5—Must be 0 


P6—Screen rectangle values block address 
(optional) 


This parameter is a longword that points to a screen rectangle values block. 
This block defines a rectangle on the screen. 


If you do not specify P6, a default rectangle that covers the entire screen is 
used. 


The following diagram shows the data structure that specifies a screen 
rectangle. 


MINX (left side value) 














0 
tonsa id 
ee 
ee 





Field Use 


MINX (left side value) Pixel value for left side of rectangle 
MINY (bottom side value) Pixel value for bottom side of rectangle 
MAXX (right side value) Pixel value for right side of rectangle 
MAXY (top side value) Pixel value for top side of rectangle 


A ae a A a ae I Sa PE OE A Ae PTD DOE eT RCO nN PNET OR eT 
DESCRIPTION The QVSS and QDSS drivers track the pointer by moving the pointer 
. cursor on the physical screen. To minimize desktop space required to 
manipulate the pointer, the driver updates the pointer cursor on the screen 
proportionally to the velocity at which the pointer is being moved on the 
desktop. 
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Enable Pointer Movement 


The driver allows a process to enable a pointer motion notification request 
to signal pointer motion within a selected area of the physical screen. A 
token is passed to the specified AST address to indicate the new pointer 
cursor physical position. An input rectangle defines the area in which the 
application is interested in pointer motion. If rectangles for pointer motion 
requests for multiple channels (or processes) overlap, priority is given to 
the first rectangle on the list. 


EXAMPLE 


10S: MOVL 
$QIow_S 


BLBS 
BRW 
208: RSB 
MOUSE_BLOCK: 


- LONG 
- LONG 
- LONG 
- LONG 


MOUSE_REGION: 
-» LONG 
- LONG 
« LONG 
- LONG 
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The following example shows how a pointer motion AST could be 
programmed. 


#IO$C_QV_MOUSEMOV, RO 
CHAN=MOUSE_CHAN, - 
FUNC=#10$_SETMODE, - 
P1=(RO),- 
P2=#MOUSE_BLOCK, - 
P6=#MOUSE_REGION 

RO, 20$ 

ERROR 


MOUSE_AST 
MOUSE_ACK 
0 
MOUSE_XY 


400 
400 
800 
800 


we Ne Ne Ne Ne Ne tO 


ENABLE MOUSE MOTION 
REGION 


+ NO ERROR IF SET 


MOUSE REGION AST 
SPECIFICATION. BLOCK 

AST ADDRESS 

AST PARAMETER 

ACCESS MODE 

NEW MOUSE CURSOR POSITION 
STORAGE 


MOUSE REGION 
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Enable User Entry 


Assigns a control AST to each user entry in an optional graphics package 
entry list. The entry at the top of the list receives a control AST when a 
cycle request occurs. A cycle request is an entry control AST request that 
includes the IO$M_QV_CYCLE function modifier. 








FORMAT SYSS$QIO_[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p1 [,p2] ,p3 [,P4] [, 5] [, pS] 

UNIQUE P1—IO$C_QV_ENAUSER (required) 

PARAMETERS This function code identifies the action the QIO performs. 


To modify the QIO action, “OR” the IO$C_QV_ENABUSER function code 
with one of the following optional function modifiers: 


Function Modifier Action 


1O$M_QV_CYCLE Removes the active entry from the beginning of the entry 
list and places it at the end of the list (lowest priority). The 
- next highest priority keyboard request then becomes the 
active keyboard request, and a control AST is delivered on its 
behalf. 


IO$¢M_QV_DELETE _ Deletes the specified entry control request. Any data 
contained in the type-ahead buffer is delivered to the 
specified AST address before the delete operation is 
executed. 


IO$SM_QV_LAST Places the specified entry control request last in the list. If 
IO$GM_QV_LAST is not specified, the request is placed first 
on the list. If an outstanding entry control request exists for 
the channel, it is updated to reflect the new priority. 


P2—Must be 0 (required) 


P3—Active entry AST specification block address 
(required) 


This parameter is a longword that points to an active entry AST 
specification block. This block specifies a user-supplied control AST 
routine that is notified when this entry becomes active. 
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The following diagram shows the data structure that specifies an active entry AST. 












AST service routine address 0 

AST parameter 4 

: 
® 

Field Use 

AST service routine address The AST service routine address is 0 if no 
AST routine is required. 

AST parameter The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

Access mode The access mode where the AST is delivered 
is maximized with the current access mode. 

0 The fourth longword must be 0. 

P4, P5, P6B—Must be 0 
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Get Keyboard Characteristics 


Obtains the keyboard characteristics for existing keyboard regions. The 
specified keyboard region is not changed and does not become the active 
keyboard region. 








FORMAT SYS$QIO_ [efn] ,chan ,[O$_SENSEMODE , [iosb] 
,[astadr] ,[astprm] ,p7 [,P2] [,P3] ,p4 [,P5] 
[,p6] 

UNIQUE P1—IO$C_QV_GETKB_INFO (required) 


PARAMETERS This function code identifies the action the QIO performs. 
P2, P3—Must be 0 


P4—Keyboard characteristics block address 
(required) 


This parameter is a longword that points to a keyboard characteristics 
block. This block receives the keyboard-related characteristics for this 
keyboard region. 


The following diagram shows the data structure where the driver returns 
the keyboard characteristics. 


enabled characteristics mask 
'. disabled characteristics mask 
keyclick volume: 


Field Use 






Enabled characteristics The first longword is a mask of characteristics that are 
mask enabled. 
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Field Use 





Disabled characteristics The second longword is a mask of characteristics that 
mask are disabled. 


The keyboard characteristics, defined by the $QVBDEF 
macro, consist of the following bits: 





Characteristic Default Meaning 
QV$M_KEY._ On Key held down 
AUTORPT automatically repeats. 
QV$M_KEY_ On Keyclick sounds on 
KEYCLICK each keystroke. 
QV$M_KEY_UDF6 Off Function keys F6 


through F10 generate 
up/down transitions. 
QV$M_KEY_UDF11 = Off Function keys F11 
through F14 generate 
up/down transitions. 
QV$M_KEY_UDF17 Off Function keys F17 | 
through F20 generate 
up/down transitions. 


QV$M_KEY_ Off Function keys HELP 

UDHELPDO and DO generate 
up/down transitions. 

QV$M_KEY_UDE1 Off Function keys E1 


through E6 generate 
up/down transitions. 


QV$M_KEY_ Off Arrow keys generate 
UDARROW up/down transitions. 
QV$M_KEY_ Off Numeric keypad keys 
UDNUMKEY generate up/down 
transitions. 
Keyclick volume The keyclick volume must be between 1 (loudest) to 8 


(softest). If you specify 0, the current system default 
keyclick volume is used. 


0 The fourth longword must be 0. 





P5, P6—Must be 0 
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Get Next Input Token 


Intercepts the next input event for an entry on a list and returns it in the 
second longword of the I/O status block. 





FORMAT 


SYS$QIO_[efn] ,chan ,IO$_ READVBLK ,iosb ,[astadr] 
,[astprm] ,[p1] ,p2 [,P3] [,P4] [, pS] [,P6] 





UNIQUE 
PARAMETERS 


P1—Must be 0 (required) 


P2—Symbolic name of list from which token Is 
intercepted (required). 


This parameter specifies the list on which the get function is performed. 
Specify one of the following lists: 


List Function Performed 


lO$C_QV_ENABUTTON Get next pointer button change. 
1O$C_QV_ENAKB Get next token entered from the keyboard. 
1O$C_QV_MOUSEMOV Get next pointer motion. 


P3, P4, P5, P6—Must be 0 





DESCRIPTION 


If the type-ahead buffer for that entry is empty, the QIO is held and then 
delivered as soon as the next token is obtained. If the type-ahead buffer is 
not empty, the first character is removed and delivered. Oniy one token is 
returned for each QIO issued. 


Regarding the decision as to where to deliver the next input token, this 
QIO preempts the AST routine for the entry. Several Get Next Input 
Token QIOs can be queued on a single entry. 


This QIO cannot be issued if the entry has an AST routine currently 
enabled. However, an AST routine can be enabled even though one or 
more of these QIOs is outstanding on the entry. 
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Get Number of List Entries 


Enables you to obtain the number of AST entries contained in any of the 
following lists: 


e Keyboard entry list 
e Pointer button transition list 
¢ Pointer motion list 


e User entry list 


DE Ra SS Se UE Ae a AE BE We aa RON aI, i a Na Eg EE A I a a rn Te ee 
FORMAT SYS$QIO_[efn] ,chan ,JO$_SENSEMODE ,iosb 
,[astadr] ,[astorm] ,p1 ,p2 ,p3 [,p4] [, 5] [, p6] 


UNIQUE P1—lIO$C_QV_GET_ENTRIES (required) 
PARAMETERS 
P2—Symbolic name of list from which you want to 


get entry count (required) 
This parameter specifies the list on which the get function is performed. 
Specify one of the following lists: 


List Function Performed 


lO$¢C_QV_ENAKB Get number of entries in the keyboard entry list 

1O$C_QV_ENABUTTON Get number of entries in the pointer button transition 
list 

lO$C_QV_MOUSEMOV Get number of entries in the pointer motion list 

lO$C_QV_ENAUSER Get number of entries in the user entry list 


P3—Address of a longword to receive the number of 
entries (required) 


P4, P5, P6—Must be 0 
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Get System Information 


Returns the address of the system information block, which a process 
can use to obtain dynamic video-related information. The address of the 
system information block does not change. Therefore, a process need only 
obtain the address once and can reference it until the process terminates. 





FORMAT 


SYSSQIO_[efn] ,chan ,IO$_SENSEMODE ,[iosb] 
,[astadr] ,[astorm] ,p7 ,p2 ,p3 [,p4] [, PS] [, p6] 





UNIQUE 
PARAMETERS 


P1—IO$C_QV_GETSYS (required) 


The function code that identifies the action that the QIO performs. 


P2—Quadword block address (required) 

This parameter is a longword that points to a quadword block to receive 
the address and length of the system information block. The structure is 
user read, kernel read/write. 


P3, P4, P5, P6B—Must be 0 





DESCRIPTION 


The system information block differs according to the system: 

¢ QVSS—QVB system information block (see Appendix A) 

¢ QDSS—QDB system information block (see Appendix B) 

Both structures contain fields that hold information about video memory. 


Some of the information is static, such as the address of onscreen memory; 
other information is dynamic, such as the current pointer position. 
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Initialize Screen 


Initializes the screen to a known state. 


DA i a na Ow ea EO Ti al eB GN Ss) 
FORMAT SYS$QIO_[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p1 [,p2] , p3] [,P4] [PS] [,p6] 





UNIQUE P1—IO$C_QV_INITIALIZE function code (required) 
PARAMETERS _s This function code identifies the action the QIO performs. 


P2, P3, P4, P5, P6—Must be 0 


a aN a TE A a aN a Sa tak Ba 

DESCRIPTION This QIO initializes the workstation screen. You must initialize the screen 
whenever you initialize a windowing system to use the QVSS or QDSS 
screen. The windowing system should issue this QIO only once, before it 
issues any other QIOs to the driver. 
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Load Compose Sequence Table 


Loads two- and three-stroke compose sequence tables. 








FORMAT SYS$QIO_ [efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 

,[astprm] ,p7 [,P2] [,P3] [,P4] [,P5] [, PS) 
UNIQUE P1—lIO$C_QV_LOAD_COMPOSE_TABLE 
PARAMETERS (required) 


This function code identifies the action the QIO performs. 


To modify the QIO action, ‘YOR’ the IO$C_QV_LOAD_COMPOSE_TABLE 
function code with the following optional function modifier: 


Function Modifier Action 


1O$M_QV_LOAD_DEFAULT If the 1OSM_QV_LOAD_DEFAULT modifier is 
— specified, this table becomes the default table for 
the entire workstation. Specify this modifier only 
once after you initialize the workstation when you 
load the first table. 


P2—Two-stroke compose sequence table size 
(optional) 


This parameter is a longword that contains the size (in Bytes of the two- 
stroke compose sequence table. 


P3—Two-stroke compose sequence table address 
(optional) 


This parameter is a longword that points to the two-stroke compose 
sequence table. Chapter 2 describes the two-stroke compose sequence 
table. 


P4—Three-stroke compose sequence table size 
(optional) 

This parameter is a longword that contains the size (in bytes) of the three- 
stroke compose sequence table. 

P5—Three-stroke compose sequence table address 
(optional) 

This parameter is a longword that points to the three-stroke compose 


sequence table. Chapter 2 describes the three-stroke compose sequence 
table. 


P6—Must be 0 
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DESCRIPTION _If only one table is to be loaded, specify values of 0 for the parameters of 
the other table. : 


A keyboard region has two tables associated with it for each type of 
compose sequence: 


e Default table—Taken from the workstation default 


e Private table—If one is loaded 





EXAMPLE The following example shows how to load a three-stroke compose sequence 
. table. 


SET_COMPOSE3_TABLE: 
MOVL #<IO$C_QV_LOAD_COMPOSE_TABLE>, RO 


SQIOW_S CHAN = KBD_CHANI, - ; CHANGE THE COMPOSE TABLE 
FUNC = #10$_SETMODE, - 
Pl = (RO), - 
P4 = #COMPOSE3_TBL_LEN, - ; three-stroke TABLE SIZE 
P5 = #COMPOSE3_TBL ; three-stroke TABLE ADDR 
BLBS RO,5$ ; NOT SET ON ERROR 
BRW ERROR ; 


583 RSB 
VCSCOMPOSE_KEYINIT COMPOSE3.TBL }; GENERATE AN 
; EMPTY TABLE 
; FILL THE TABLE HERE 
t 
VCSCOMPOSE_KEY <*a/A/>,<*a/"/>,,<*xc4> 
VCSCOMPOSE_KEY <‘’a/A/>,<*a/'/>,,<*xcl> 
VCSCOMPOSE_KEY <‘a/A/>,<‘a/*/>,,<*xc5> 
VCSCOMPOSE_KEY <*a/A/>,<‘*a/A/>,<@> 
VCSCOMPOSE_KEY <%’a/A/>,<*a/E/>,,<*xc6> ; ORDER SENSITIVE 
VCSCOMPOSE_KEY <*’a/A/>,<‘a/*%/>,,<*xc2> 
VCSCOMPOSE_KEY <*a/A/>,<‘a/_/>,,<*xaa> 


VCSCOMPOSE_KEYEND COMPOSE3_TBL_LEN END THE TABLE 
AND DETERMINE ITS 


LENGTH 


~e ~e we 
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Load Keyboard Table 


Loads a keyboard table. 





FORMAT 


SYSSQIO_ [efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 [,p4] [,P5] [,p6] 





UNIQUE 
PARAMETERS 


P1—IO$C_QV_LOAD_KEY_TABLE (required) 
This function code identifies the action the QIO performs. 


To modify the QIO action, ‘“OR” the IO$C_QV_LOAD_KEY_TABLE 
function code with the following optional function modifier: 


Function Modifier Action 


IO$M_QV_LOAD_DEFAULT if the (O$M_QV_LOAD_DEFAULT modifier is 
specified, this table becomes the workstation 
default. Specify this modifier only once when 
you load the first table after you initialize the 
workstation. 


P2—Keyboard table size (required) 
This parameter is a longword that contains the size (in bytes) of the 
keyboard table. 


P3—Keyboard table address (required) 
This parameter is a longword that points to the keyboard table. Chapter 2 
describes keyboard tables. 


P4, P5, P6é—Must be 0 





DESCRIPTION 


Each window has two associated tables: 
e Default table—Taken from the workstation default 


e Private table—If one is loaded 
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EXAMPLE 


SET_FRENCH_KB: 
MOVL #<I0$ 
$QIOW_S CHAN 

FUNC 

Pl 
P2 
P3 


ot 


BLBS RO,5$8 
BRW ERROR 
5S: RSB 
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The following example shows how to load a keyboard table. 


C_QV_LOAD_KEY_TABLE>, 
= KBD_CHANI, - 

= #10$_SETMODE, - 
(RO), ie 
#KB_LAYOUT_TBL_LEN, - 
#KB_LAYOUT_TBL 


CHANGE THE KEYBOARD 
LAYOUT 


KEYBOARD TABLE SIZE 
KEYBOARD TABLE 
ADDRESS 

NO ERROR IF SET 
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Modify Keyboard Characteristics 


Changes the keyboard characteristics for an existing keyboard region. 





FORMAT SYS$QIO _[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,pT [,p2] , P3] [,P4] [, 5] [, p6] 





UNIQUE P1—IO$C_QV_MODIFYKB (required) 
PARAMETERS - . This function code identifies the action the QIO performs. 


To modify the QIO action, ‘YOR’ the IO$C_QV_MODIFYKB function code 
with the following optional function modifier: 


Function Modifier Action 


1IO$M_QV_ACTIVE Removes the active keyboard from the beginning of the 
keyboard request list and places it at the end of the 
list (lowest priority). The keyboard region just modified 
becomes the active keyboard request and a control AST 
is delivered on its behalf. 


P2—Keystroke AST specification block address 
(optional) 


This parameter is a longword that eins to a keystroke AST specification 
block. This block specifies a user-supplied AST routine that is notified 
each time a keystroke occurs. 


The following diagram shows the data structure that specifies a keystroke 
AST 
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Field 


AST service routine address 


AST parameter 


Access mode 


Input token address 


Use 


The AST service routine address Is 0 if no 
AST routine is required. If no AST routine is 
specified, input is stored in the type-ahead 
buffer and delivered either when an AST 
region is declared or when a Get Next Input 
Token QIO is issued. The type-ahead buffer 
holds 32 input tokens or characters. 


The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 


The access mode where the AST is delivered 
is maximized with the current access mode. 


This is the address of a longword that 
receives an input token when an AST routine 
is called. Word 0 of the longword contains 
token or character data. Values from 0 

to 255 map into the Digital multinational 
character set. Values from 256 to 512 map 
function keys into token values. Word 1 of 
the longword contains control information; 
bit 15 defines the status of a token (1 equals 
down, 0 equals up). By default, an AST is 
signaled only on a down transition. 


P3—Keyboard request AST specification block 


address (optional) 


This parameter is a longword address that points to a keyboard request 
AST specification block. This block specifies a control AST routine that 
is notified when a keyboard request becomes active. A keyboard request 
becomes active when the active keyboard owner is deleted or a cycle 
request causes the keyboard request to become active. No control AST is 
delivered when the new request is already active or the owning process 


issued the cycle request. 


The following diagram shows the data structure that specifies a keyboard 


request AST. 


AST service routine address 
AST parameter 
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Field Use 
AST service routine address The address of the AST service routine is 0 if 


no AST routine is required. If no AST routine 
is specified, input is stored in the type-ahead 
buffer and delivered either when an AST 
region is declared or when a Get Next Input 
Token QIO is issued. The type-ahead buffer 
holds 32 input tokens or characters. 


AST parameter The user-defined AST parameter is delivered 
to the AST routine. The driver does not 
examine it. 

Access mode The access mode where the AST is delivered 


is maximized with the current access mode. 
0 The fourth longword must be zero. 


P4—Keyboard characteristics block address 
(optional) 


This parameter is a longword address that points to a keyboard 
characteristics block, which describes keyboard-related characteristics to 
be enabled or disabled for the keyboard region when the keyboard region 
becomes active. 


The default characteristics are those specified in the systemwide 
characteristics block, which you can modify with the Modify Systemwide 
Characteristics QIO. The current systemwide characteristics are stored in 
the characteristics field of the QVB. 


The following diagram shows the data structure that specifies the keyboard 
characteristics. 






wr cena id 
Se 
ne id 
a 


Field Use 
Enabled characteristics The first longword is a mask of characteristics to 
mask enable. 
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Field 


Disabled characteristics 
mask 


Use 


The second longword is a mask of characteristics to 


disable. 


The keyboard characteristics, defined by the $QVBDEF 
macro, consist of the following bits: 


Characteristic Default Meaning 
QV$M_KEY_ On Key held down 
AUTORPT automatically repeats. 
QV$M_KEY_ On Keyclick sounds on 
KEYCLICK each keystroke. 
QV$M_KEY_UDF6 Off Function keys F6- 
F10 generate up/down 
transitions. 
QV$M_KEY_ Off Function keys F11- 
UDF 11 F14 generate up/down 
transitions. 
QV$M_KEY_ Off Function keys F17- 
UDF 17 F20 generate up/down 
transitions. 
QV$M_KEY_ Off Function keys HELP 
UDHELPDO and DO generate 
up/down transitions.. 
QV$M_KEY_UDE1 Off Function keys E1- 
E6 generate up/down 
transitions. 
QV$M_KEY_ Off Arrow keys generate 
UDARROW up/down transitions. 
QV$M_KEY_ Off Numeric keypad keys 
UDNUMKEY generate up/down 


transitions. 


The keyclick volume must be between 1 (loudest) and 
8 (softest). If you specify 0, the current system default 
keyclick volume is used. 


0 The fourth longword must be 0. 


Keyclick volume 


P5, P6-—Must be 0 
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Modify Systemwide Characteristics 


Changes the systemwide windowing characteristics. 








FORMAT SYS$QIO _[efn/ chan ,1O0$_SETMODE , [iosb] ,[astadr] 
,astprm] ,p7 [,p2] [,P3] [,P4] [PS] PS) 
UNIQUE P1—lO$C_QV_MODIFYSYS (required) 
PARAMETERS _ This function code identifies the action the QIO performs. 
P2, P3—Must be 0 


P4—System characteristics block address 

(optional) 

This parameter is a longword address that points to a system characteristics 
block, which specifies system-related characteristics to enable or disable. 


The following diagram shows the data structure that specifies system 
characteristics. 


Field Use 






Enabled characteristics The first longword is a mask of characteristics to enable. 
mask 
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Field 


Use 





Disabled characteristics 
mask 


Keyclick volume 


Screen saver timeout 
value 


The second longword is a mask of characteristics to 


disable. 


The system characteristics, defined by the $QVBDEF 
macro, consist of the following bits: 


Characteristic 
QV$M_KEY_ 
AUTORPT 


QV$M_KEY_ 
KEYCLICK 


QV$M_KEY_UDF6 


QV$M_KEY_ 
UDF 11 


QV$M_KEY_ 
UDF17 


QV$M_KEY_ 
UDHELPDO 


QV$M_KEY_UDE1 


QV$M_KEY_ 
UDARROW 

QV$M_KEY_ 
UDNUMKEY 


QV$M_SYS_ 
SCRSAV 


Default Meaning 


On Key held down 
automatically repeats. 


On Keyclick sounds on each 
keystroke. 


Off Function keys F6- 
F10 generate up/down 
transitions. 


Off Function keys F11- 
F14 generate up/down 
transitions. 


Off Function keys F17- 
F20 generate up/down 
transitions. 


Off Function keys HELP and 
DO generate up/down 
transitions. 


Off Function keys E1- 
E6 generate up/down 
transitions. 


Off Arrow keys generate 
up/down transitions. 


Off Numeric keypad keys 
generate up/down 
transitions. 


On Video output to monitor 
is disabled if no input 
activity occurs in the time 
specified in the fourth 
longword. Any keystroke, 
pointer button transition, 
or pointer motion resets 
the timer and reactivates 
a disabled screen. 


The keyclick volume must be a value from 1 (loudest) to 
8 (softest). Default is 3. 


This value represents the number of minutes of inactivity 
that must elapse before the screen saver is activated. 
The value must be from 1 to 1440. If the value is 0, the 
timeout value stays unchanged. Default is 15. 
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P5—Pointer characteristics block address 
(optional) 


This parameter is a longword address that points to a pointer characteristics 
block that specifies the pointer-related characteristics you enable or disable. 


The following diagram shows the data structure that specifies pointer 
characteristics. 










enabled characteristics mask 0 
disabled characteristics mask 4 
ee eee 
a # 
Field Use 
Enabled characteristics mask The first longword is a mask of characteristics to 
be enabled. 


Disabled characteristics mask The second longword is a mask of characteristics 
to be disabled. 


The pointer characteristics, defined by the 
$QVBDEF macro, consist of the following bits: 


Characteristic Meaning 

QV$M_PTR_ Inverts buttons on mouse or 

LEFT_HAND puck. (Buttons 1 and 3 are’ 
switched.) 

QV$M_PTR_ Inverts buttons on stylus. 

INVERT_STYLUS (Buttons 1 and 3 are 
switched.) 

0 Must be 0 
Must be 0 


P6—Must be 0 
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EXAMPL The following example shows how the system windowing characteristics 
could be changed. 


SET_CHARACTERISTICS: 


MOVL #IOSC_QV_MODIFYSYS, RO CHANGE SYSTEM 


=e we 


SQIOW_S CHAN=SYS_CHAN1,- CHARACTERISTICS 
FUNC=#I0$_SETMODE, - 
Pl = (RO);- 
P4 = #CHAR_BLOCK 
BLBS RO, 10$ ; NO ERROR IF SET 
BRW ERROR 
CHAR_BLOCK: ; CHARACTERISTICS BLOCK 


-LONG <QVS$M_SYS_AUTORPT!QVSM_SYS_KEYCLICK> ; ENABLE 
} THESE CHARACTERISTICS 
.LONG <QVSM_SYS_UDF6!QVSM_SYS_UDARROW> ; DISABLE 
} THESE CHARACTERISTICS 
.LONG 5 ; KEYCLICK VOLUME 
.LONG 30 ; SCREEN SAVER TIMEOUT 
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Revert to Default Compose Table 


Reverts to the two-stroke or three-stroke default compose table. 





FORMAT 


SYSS$QIO_[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p7 [,p2] [, p3] [ p4] [, pS] [, p6] 





UNIQUE 
PARAMETERS 


P1—IO$C_QV_USE_DEFAULT_TABLE (required) 


This function code identifies the action the QIO performs. 


To modify the QIO action, “OR” the IO$C_QV_USE_DEFAULT_TABLE 
function code with one of the following optional function modifiers: 


Function Modifier Action 


IO$M_QV_COMPOSE2 Reverts to the two-stroke default compose table. 
1O$M_QV_COMPOSE3 Reverts to the three-stroke default compose table. 


P2, P3, P4, P5, P6—Must be 0 





DESCRIPTION This QIO also returns the space used by a private table (if one was loaded) 
to pool. 
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Revert to Default Keyboard Table 


Reverts to the default keyboard table. 





FORMAT SYS$QIO_[efn] ,chan ,IO$_SETMODE ,[iosb] ,[astadr] 
,[astprm] ,p7 [,p2] [,P3] [,04] [,P5] [, p6] 





UNIQUE P1—lIO$C_QV_USE_DEFAULT_TABLE!IO$M_QV_KEYS 
PARAMETERS (required) 


This function code identifies the action the QIO performs. The exclamation 
point (!) indicates that you must OR the IO$C_QV_USE_DEFAULT_TABLE 
function code and the IO$M_QV_KEYS function modifier to perform the 
QIO. 


P2, P3, P4, P5, P6B—Must be 0 





DESCRIPTION This QIO also returns the space used by a private table (if one was loaded) 
to pool. 
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4.1 





QDSS-Specific QIO Interface 


This chapter describes the QIOs you use only with the QDSS driver. The 
QIO descriptions appear in alphabetical order. Table 4-1 organizes the 
QIOs in functional groups. 


Table 4-1 QDSS QIO Functional Groups 


Functional Group QiO Name 
Controlling Color { Set Color Characteristics \ 
Set Color Map Entries 


Defining Viewports { Define Viewport Region } 


Delete Deferred Queue Operation 
Execute Deferred Queue 

Hold Viewport Activity 

Insert DOP 

Release Hold 

Resume Viewport Activity 

Start Request Queue 

Stop Request Queue 

Suspend Occluded Viewport Activity 
Suspend Viewport Activity 


Get Color Map Entries 
Get Free DOPs 

Get Viewport ID 

Notify Deferred Queue Full 


Manipulating the DOP Queues 


Obtaining Information 





Transferring Bitmaps Load Bitmap 
Read Bitmap 
Write Bitmap 
How to Use This Chapter 


Before you call QIOs, read Chapters 1 and 2 and familiarize yourself with 
Appendices A, B, and H. 


¢ Chapters 1 and 2 describe the general operation of QIOs. 


e Appendices A and B contain diagrams and descriptions of the data 
types you pass to the driver through the P1 to P6 parameters. 


e Appendix H describes the SYS$QIO system service. 


Then, as you call QIOs, refer to the descriptions in this chapter. 


QDSS-Specific QIO Interface 





4.2 QIO Description Format 


4-2 


The QIO descriptions follow a strict format. The main headings in each 
QIO description and the type of information that appears there follow. 


QIO Name—Name of the QIO. 
Overview—Brief description of the operation the QIO performs. 


Format—Format of the call you must pass to SYS$QIO to perform the 
desired operation. 


Arguments in brackets are optional. Some programming languages, 
such as MACRO, allow you to omit optional arguments; the assembler 
supplies a default value of 0. Some other programming languages, 
such as FORTRAN, do not allow you to omit optional arguments; 

you must pass a value of 0 for any unspecified argument. Check the 
programming language documentation to see how the language handles 
optional arguments. 


Unique Parameters—Routines that pass information to the driver 
through $QIO P1 to P6 parameters, which are noted as required or 
optional. 


Description— Additional QIO operation information. 


Example—QIO example. 
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Define Viewport Region 


Define Viewport Region 


Creates or changes the update regions that compose a viewport. 


SA EPL LENS, LIT TET BT a a CT Te a TET) 





FORMAT SYSSQIO_[efn] ,chan, |O$_SETMODE , [iosb] ,[astadr] 

,[astprm] ,p7 ,p2 ,p3 ,p4 [,p5] [,p6] 
UNIQUE P1—IO$C_QD_SET_VIEWPORT_REGIONS 
PARAMETERS (required) 


This function code identifies the action the QIO performs. 


P2—Update region definition buffer address 
(required) 


This longword points to the buffer that describes the update regions that 
define the viewport. 


The following diagram shows the data structure that specifies each region. 


The following list describes the contents of each field in the update region 
definition block. 


Field | Use 


URD$W_X_MIN Viewport-relative X coordinate of the lower left corner of 
defined region (in pixels) 


URD$W_Y_MIN Viewport-relative Y coordinate of the lower left corner of 
defined region (in pixels) 


URD$W_X_MAX Viewport-relative X coordinate of the upper right corner of 
defined region (in pixels) 


URDS$SW_Y_MAX Viewport-relative Y coordinate of the upper right corner of 
defined region (in pixels) 


URD$W_X_BASE Absolute X coordinate from lower left corner (in pixels) 
URD$W_Y_BASE Absolute Y coordinate from lower left corner (in pixels) 


P3—Update region definition buffer length 


(required) 
This parameter specifies the predefined constant URD$C_LENGTH 
multiplied by the number of update regions. 


P4—Viewport ID (required) 

This parameter is the ID of the viewport you are defining dr changing. 
Use the Get Viewport ID QIO to obtain a unique viewport ID for any new 
viewport you want to define. 


P5, P6—Must be 0 


QDSS-Specific QIO Interface 
Define Viewport Region | 





DESCRIPTION 


This function creates or modifies viewport update region definitions. The 
viewport that appears on the screen can consist of a number of update 
regions. 


To access a viewport, you must call this function once. (A viewport must 
contain at least one update region.) If a viewport contains a number of 
regions, you make this call once, specifying a URD buffer (an array or 


record) that contains all the URDs. 


Before you call Define Viewport Region QIO, you must call Stop Request 
Queue QIO. 


A viewport management system uses this function to control the screen 
layout. When a drawing operation is executed, the function is performed 
to each update region specified in the viewport definition. 
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Delete Deferred Queue Operation 


Delete Deferred Queue Operation 


Deletes any entries in the specified deferred queue. 





FORMAT 


SYS$QIO_ [efn] ,chan, [O$_SETMODE , [iosb] ,[astadr] 
,fastprm] ,p7 ,p2 [,p3] [p4] [pS] L p6] 





UNIQUE 
PARAMETERS 


P1—IO$C_QD_DELETE_DEFERRED (required) 

This function code identifies the action the QIO performs. 
P2—Viewport_id (required) 

This parameter is the ID of the viewport associated with the deferred 


queue. The Get Viewport ID QIO returns the viewport ID during the 
creation of the viewport. 


P3, P4, P5, P6—Must be 0 





DESCRIPTION 


This function deletes all operations on the deferred queue associated with 
the specified viewport. 


Typically, you use this QIO when you pop an occluded viewport. Call it 
after you execute an Execute Deferred Queue QIO for vet. update region 
previously stored in processor memory. 
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Execute Deferred Queue 


Processes any DOPs on the specified viewport deferred queue. 





FORMAT 


SYSSQIO [efn] ,chan , lO$_ SETMODE ,[iosb] , [astadr] 
,[astorm] pt ,P2 [,P3] [,P4] [,P5] Lp] 





UNIQUE 
PARAMETERS 


P1—IO$C_QD_EXECUTE_DEFERRED (required) — 


This function code identifies the action the QIO performs. 


P2—Viewport_id (required) 
This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during the creation of the viewport. 


P3, P4, P5, P6—Must be 0 





DESCRIPTION 


This function executes all operations on the deferred queue. All operations 
executed when the viewport was not accessible are replayed to the 
specified viewport buffer. 


The driver puts operations on the deferred queue when an operation is 
specified for a screen region that the QDSS hardware cannot currently 

access. The QDSS hardware cannot access a region stored in processor 
memory. 


Operations on the deferred queue are executed into the currently defined 
set of region descriptors. If the buffer identifies visible screen locations, 
some unusual visual effects might occur. 
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Get Color Map Entries 


Get Color Map Entries 


Returns the values in the color map. 








FORMAT SYS$QIO_[efn] ,chan ,IO$_SENSEMODE ,fiosb] 
,[astadr] ,[astprm] ,p1 ,p2 ,p3 ,p4 [, pS] [, 6] 

UNIQUE P1—lIO$C_QD_GET_COLOR (required) 

PARAMETERS _Lhis function code identifies the action the QIO performs. 


To modify the QIO action, “OR” the IO$C_QD_GET_COLOR function 
code with one of the following optional function modifiers: 


Function Modifier Action 


IO$M_QD_INTENSITY Gets a map entry on an intensity system. 

IO¢M_QD_RESERVED_COLORS Interprets the starting color map entry (P4) as 
the IO$C_QD_TWO_COLOR_CURSOR (set 
two-color cursor) parameter if the IO$M_QD_ 
RESERVED_COLORS modifier is specified. 
The buffer here contains two map entries’ 
worth of data: two words for intensity systems, 
six words for color systems. 


P2—Color buffer address (required) 
This longword points to a buffer to hold the returned entries of the color 
map. 


The size of the color buffer depends on the system: 


¢ Color system—The buffer must have an ‘RGB triple’ for each map 
entry you want to read. An “RGB triple’ contains three word-long 
values—one for red, one for green, and one for blue. For example, for 
five color map entries, the color buffer must be 15 words long. 


e Intensity system—The buffer must have a single word-long value for 
each map entry you want to read. For example, for five color map 
entries, the color buffer must be five words long. 


Only the eight most significant bits are used for color definition. 


P3—Length of the color buffer, in bytes (required) 


The multiple you use depends on the system: color-6, intensity-2. 


P4—Starting color map entry must be 0 (required) 
This parameter is the color map index you use for the first RGB or intensity 
value specified in the buffer. 


P5, P6—Must be 0 
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Get Color Map Entries 


DESCRIPTION This function enables an application to read the color map. Color map 
information is stored in the QDB, which you access by issuing a Get 
System Information QIO. Appendix B describes the QDB. 
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Get Free DOPs 


Indicates how many DOPs must be on the specified return queue for 
request queue processing to continue. 








FORMAT SYS$QIO_[efn] ,chan,IO$_SENSEMODE , [iosb] 
,[astadr] ,[astorm] ,p1 ,p2 ,p3 ,p4 [,p5] [, 6] 

UNIQUE P1—IO$C_QD_GET_FREE_DOPS (required) 

PARAMETERS This function code identifies the action the QIO performs. 


P2—Number of DOPs (required) 


This parameter is the number of DOPs on the return queue that the driver 
should wait for before resuming request queue processing. 


P3— Queue flag (required) 
This flag specifies which return queue to await: 
e 0—Normal (small DOP) queue 


e 1—Large DOP queue 
P4—Viewport_Id (required) 


This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during the creation of the viewport. 


P5, P6—Must be 0 


DESCRIPTION 


This function causes a process to wait until a specified number of drawing 
output primitives (DOPs) are on the specified viewport return queue. 


Use this function to suspend operations until the driver returns a set of 
DOPs. This way, the storage space for the DOPs can be reused. Note that 
you specify the number and size of the DOPs to await. 


When this QIO completes and/or the associated AST is fired, the 
application uses the REMQUE instruction to allocate storage from the 
specified return queue. Sometimes, this QlIO completes and nothing is on 
the return queue. When this occurs, reissue the QIO until the REMQUE 
succeeds. 
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Get Viewport ID 


Get Viewport ID 


Returns a unique viewport identifier called a viewport ID. 








FORMAT SYSSQIO_[efn] ,chan , |O$_SENSEMODE ,|[iosb] 
,[astadr] ,[astprm] ,p1 ,p2 ,p3 [,p4] [, 05] [, p6] 

UNIQUE P1—IO$C_QD_GET_VIEWPORT_ID (required) 

PARAMETERS _ This function code identifies the action the QIO performs. 


P2—Viewport ID buffer address (required) 


This longword points to a longword buffer where the driver returns the 
viewport ID. 


P3—Viewport ID buffer length, in bytes 


The value of this parameter must be 4. 


P4—Alternate return queue address (optional) 

By default (if this parameter is 0), each viewport is associated with two 
return queues. You can specify an address for an alternate return queue. 
For example, you might want to share return queues on a per-process basis 
instead of a per-viewport basis or you might want a systemwide return 
queue. 


The following diagram shows the data structure that specifies an alternate 
return queue. 


The following list describes the contents of each field in the request queue 
definition. 


Field Use 

RET$L_RETURN_FLINK Forward link for the ordinary return queue 

RET$L_RETURN_BLINK Backward link for the ordinary return 
queue 

RET$L_RETURN_LARGE_FLINK Forward link for the large DOP return 
queue 

RET$L_RETURN_LARGE_BLINK Backward link for the large DOP return 
queue 

RET$W_LARGE_DOP_SIZE Size of a DOP returned to the large DOP 
return queue 

RET$W_SMALL_DOP_SIZE Size of a DOP returned to the ordinary 
return queue 

RET$L_APPLICATION_RESERVED A longword reserved for use by the 
application 


P5, P6—Must be 0 
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DESCRIPTION 


This function returns the unique viewport identifier, which must be 
supplied as a parameter to several QIO functions. Note that this identifier 
is also the address of the DOP queue data structure (that contains the 
request queue and the return queue structures). 


Call this function at viewport creation time after you have an assigned 
channel, before you call any function that requires a viewport ID. Call it 
only once for each channel; multiple calls result in multiple viewports. 
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Hold ENS Activity 


Stops activity on all viewports except the systemwide viewport. 





FORMAT SYS$QIO_[efn] ,chan, |O$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p7 [,p2] [,P3] [,P4] LPS] [ pé] 





UNIQUE P1—IO$C_QD_HOLD (required) 
PARAMETERS This function code identifies the action the QIO performs. 


P2, P3, P4, P5, P6—Must be 0 





DESCRIPTION ae function stops all activity on all viewports except the systemwide 
viewport. Use this function when you move a viewport or implement a 
hold screen function. 
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Insert DOP 


Inserts a DOP on the request queue of the specified viewport. Optionally, 
it notifies the caller of a request queue entry completion. 





FORMAT 


SYSSQIO [efn] ,chan 
O$_QD_WRITE!O$M_QD_INSERT_DOP 
,[iosb] ,[astadr] ,fastorm] ,o01 ,p2 ,p3 [,p4] 
[,P5] [pe] 





UNIQUE 
PARAMETERS 


P1—Address of the DOP entry (required) 
This longword points to the DOP entry for which you want completion 
notification. 


P2—DOP entry length (required) 
This longword contains the length of the DOP you are inserting into the 
queue. 


P3—Viewport_id (required) 


This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during the creation of the viewport. 


P4, P5, P6é—Must be 0 





DESCRIPTION | 


NOTE: The exclamation point (!) in the function code above indicates that you 


must ‘““OR”’ IO$_QD_WRITE and IO$M_QD_INSERT_DOP to perform the 
Insert DOP QIO. 


The Insert DOP QIO enables you to enter a drawing operation primitive 
(DOP) on the request queue of a specified viewport. If you specify the 
IOSB parameter, the system notifies your application when the request 
queue entry finishes executing. 


You can use the Insert DOP to synchronize drawing. If you insert a Stop 
Viewport Activity DOP on the queue (rather than issuing a Stop Request 
Queue QIO), you guarantee that the DOPs inserted before the stop are 
executed. 


Use this QIO only when your application requires notification that the 
request queue entry has finished executing. An INSQUE instruction or a 
UISDC$QUEUE_DOP routine is much more efficient. 
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Load Bitmap 


Load Bitmap 


Makes a bitmap available for use by a subsequent text, patterned line, 
move, or fill operation. 





FORMAT 


SYS$QIO_[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astorm] ,p1 ,p2 ,p3 ,p4 ,p5 ,p6 





UNIQUE 
PARAMETERS 
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P1—IO$C_QD_LOAD_BITMAP (required) 


This function code identifies the action the QIO performs. 


To modify the QIO action, ‘OR’ the IO$C_QD_LOAD_BITMAP function 
code with the following optional function modifier: 


Function Modifier Action 


lO$¢M_QD_SYSTEM_WIDE Defines a bitmap that lasts for the life of the 
system. (By default, the bitmap is invalid after the 
channel it is originally returned on is deassigned.) 


P2—Address of the bitmap block (required) 

This longword points to the area of processor memory that describes the 
desired bitmap. You can also specify a zero in this parameter to postpone 
dynamic loading of the bitmap (see the Description section for details). 


P3—Bitmap block length, in bytes (required) 
This longword contains the length of the bitmap block in bytes. This value 
must be a multiple of 2. 


P4—Address of a longword for the returned bitmap 
ID (required) 


This longword is where the driver returns the bitmap ID. Subsequent 
drawing operations reference the loaded bitmap with the bitmap ID. All 
viewports and processes using the bitmap should refer to the bitmap with 
this bitmap ID. 


P5—Bitmap width, in pixels (required) 

This longword contains the width of the bitmap in pixels. The maximum 
bitmap width is 1024. If the bitmap is a single bit per pixel, you must 
specify a multiple of 16. 


P6—Bits per pixel (required) 
This longword contains the number of bits per pixel. Currently 1 and 8 are 
supported: 


e 1—When a foreground and background color are sufficient (that is, for 
writing text) 


¢ 8—When you want the full use of color (that is, for natural images) 
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DESCRIPTION The Load Bitmap QIO makes a bitmap available to a drawing operation. 
Bitmaps specify the following features: 


Fonts 

Line styles 
Fill patterns 
Images 


You load a bitmap from VAX memory to offscreen memory. Once the 
bitmap is in offscreen memory, drawing operations can access it with 
the bitmap ID. You load the bitmap only once each time the system is 
bootstrapped (unless you explicitly delete it with the Delete Bitmap DOP). 


Passing the Bitmap 


You must pass the bitmap to Load Bitmap in specific form because it is 
addressed with the X,Y coordinates rather than a single index. 


Bitmap storage is defined in blocks of video memory. The size of a bitmap 
block depends on whether you use a single-plane or multiplane image. 


¢ Single-plane bitmap—Blocks are 70 bits by 1024 bits. Think of them as 
70 lines, each 128 bytes wide. 


¢ Multiplane bitmap—Blocks are 35 bits by 8180 bits. Think of them 
as 35 lines, each 1024 bytes long. Each consecutive eight bits in a 
line describes one pixel (in four-plane systems the high four bits are 
ignored). 


If a bitmap requires more room than can be provided by a single bitmap 
block, store the bitmap in multiple blocks by getting a separate bitmap ID 
for each block and tracking them in your application. 


Bitmaps are passed in blocks to the driver as follows: 


¢ Each bitmap character (glyph) is stored in a rectangle within the bitmap. 
Glyphs are stored sequentially and can be packed to the bit; however, 
it is more efficient to start each character on a byte boundary. (The 
nature of multiplane bitmaps is such that this occurs naturally.) 


e If the total width of all glyphs exceeds the bitmap block limit, you must 
use another bitmap block, which you load separately. 


e Any unused portion of a single-plane bitmap line must be padded with 
zeros to the nearest word boundary. (Again, the nature of multiplane 
bitmaps is such that this occurs naturally.) 


Figure 4-1 shows a large font that uses more than one single-plane bitmap 
block. Each character is 32 bits high by 40 bits wide. (To include the 
lowercase letters, you have to use another bitmap block.) Notice that the 

a characters are aligned on word boundaries for better performance. If space 
is a greater consideration than performance, you can pack the characters 
in each bitmap block. Remember, your application must load each block 
separately and track the different bitmap IDs. 
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Figure 4-1 Large Font Defined Across Bitmap Blocks 
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Loading the Bitmap 
Use Load Bitmap in two ways: 


1 The bitmap is copied from the user buffer into a driver-maintained 
buffer. When the application accesses the bitmap, it is copied from the 
driver-maintained buffer into offscreen memory. 


¢ To have the driver maintain the bitmap, specify the address of the 
bitmap in process memory as the bitmap address parameter. 


¢ To access the bitmap in a subsequent DOP, load the bitmap_ID 
field of the DOP Common block with the bitmap ID returned by 
Load Bitmap. The system handles the storage of this bitmap. 


¢ When the system manages bitmap storage, it uses the bitmap 
glyph as a backing store address if it must swap the bitmap out 
of offscreen memory. That is, when the bitmap is accessed, the 
system uses the address in the bitmap glyph to swap the bitmap 
back into offscreen memory. 


2 A handle (identifier) is created for the bitmap, but the application must 
_ supply the bitmap when it is accessed. 


¢ To load a bitmap dynamically, specify zero as the bitmap address 
parameter, but specify the correct length, width, and bits-per-pixel. 
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¢ To access the bitmap in a subsequent DOP, load the bitmap_ID 
field of the DOP Common block with the bitmap ID returned by 
Load Bitmap and load the bitmap_glyph field of the DOP Common 
block with the address of the bitmap in processor memory. 


e¢ When you specify a bitmap address of 0 and put the actual address 
in the bitmap_glyph field, you save system resources. The bitmap 
is not loaded until it is accessed, and the application, not the 
_ system, is responsible for saving the bitmap (when it is swapped 
out, it is unknown by the system). 


The second method saves space because a bitmap is not loaded into 
offscreen memory until an application accesses it. 


Systemwide Bitmaps 


Usually, a bitmap is defined as temporary. That is, the bitmap ID 
associated with it is not valid once you deassign the channel on which 
it was loaded. To define a bitmap to last for the life of the system, issue 
this QIO using the IO$M_QD_SYSTEM_WIDE function modifier. 
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Notify Deferred Queue Full 


Notifies the application when a deferred queue is full. 





FORMAT 


SYSSQIO__[efn] ,chan ,LO_$SENSEMODE , [iosb] 
,[astadr] ,[astorm] ,p7 ,p2 ,p3 [, 4] [05] [, 6] 





UNIQUE 
PARAMETERS 


P1—IO$C_QD_DEFERRED_HOLD (required) 


This function code identifies the action the QIO performs. 


P2—Waiting period (required) 

This longword contains the number of 80-millisecond intervals to wait 
after the queue is full before notification. (One second is equivalent to 
seventeen 80-millisecond intervals.) | 


P3—Viewport_id (required) 


This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during viewport creation. 


P4, P5, P6—Must be 0 





DESCRIPTION 


This function notifies an application that the deferred queue is full. The 
number of deferred drawing operations for any one viewport is limited, so 
a viewport cannot consume system resources. 


When an application is notified of a full queue, it can load the viewport into 
memory, execute the deferred operations and delete the deferred queue to 
free up memory. If necessary, the application can then put the viewport 
back in a deferred state. . 


Notification can be by QIO AST, an event flag, or a wait. 
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Read Bitmap 


Copies data from video memory to a user-specified buffer in VAX memory 
and performs bitmap-to-bitmap transfers. 





FORMAT 


SYS$QIO_[efn] ,chan ,IO$_QDREAD , [iosb] ,[astadr] 
,[astprm] ,p7 ,p2 ,[p3] ,p4 ,p5 [, p6] 





UNIQUE 
PARAMETERS 


P1—Buffer address (required) 

This parameter is the buffer address in VAX memory where the driver 
should copy the bitmap. This buffer must be large enough to hold the 
bitmap specified by P4. For a bitmap-to-bitmap transfer, specify a 0 in this 
parameter. 


P2—Buffer length 
This longword contains the length in bytes of the buffer specified by P1. 


P3—Must be 0 


P4—Transfer parameter block (required) 
The transfer parameter block (TPB) describes the bitmap to be read into 
VAX memory. The TPB contains: | 


¢ Coordinates for the lower left corner of the bitmap 
¢ Bitmap height and width 
e Predefined constant indicating the type of transfer 


e For a bitmap-to-bitmap transfer, the coordinates for the lower left 
corner of the target bitmap 


The following diagram shows the data structure that specifies the transfer 
parameters. 


The following table lists the contents of each field in the Transfer Parameter 
block. 


4-19 


QDSS-Specific QIO Interface 


Read Bitmap 


Field Use 


TPBS$B_TYPE Type of transfer being performed, either bitmap- 
to-processor (BTP) or bitmap-to-bitmap (BTB). 
Use the constants defined later to load this field. 


TPB$B_SIZE - Reserved to Digital 

TPBS$W_X_SOURCE X coordinate of lower left corner of source bitmap 

TPB$W_Y_SOURCE Y coordinate of lower left corner of source bitmap 

TPB$W_WIDTH Width of source bitmap 

TPBSW_HEIGHT Height of source bitmap 

TPBSW_X_TARGET X coordinate of lower left corner of target bitmap 

(only specified for bitmap-to-bitmap transfer) 

TPB$W_Y_TARGET Y coordinate of lower left corner of target bitmap 
(only specified for bitmap-to-bitmap transfer) 

TPBSW_X_TARGET_VEC1 Reserved to Digital 

TPBS$W_Y_TARGET_VEC1 Reserved to Digital 

TPBSW_L_TARGET_VEC1 Reserved to Digital 

TPBSW_X_TARGET_VEG2 Reserved to Digital 

TPB$W_Y_TARGET_VEC2 Reserved to Digital 

TPBSW_L_TARGET_VEC2 Reserved to Digital 


The following table defines the constants in conjunction with the TPB. 


Constant . Value 

TPB$C_BITMAP_XFR Bitmap-to-bitmap transfer 

TPB$C_SOURCE_ONLY BTP or PTB transfer 

TPB$C_SOURCE_LENGTH Structure length for BTP or PTB transfers 

TPB$C_BITMAP_XFR_LENGTH Structure length for a bitmap-to-bitmap 
transfer 

TPB$C_LENGTH Full length of TPB structure 


P5—TPB length (required) 


This longword contains the length in bytes of the transfer parameter block 
specified in P4. 


P6—Must be 0 





DESCRIPTION 
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The Read Bitmap QIO reads data from the QDSS video memory into 
a specified buffer in VAX memory. This function transfers all available 
planes of memory at once. If this operation is to affect more than one 
viewport, it must be preceded by a Stop Request Queue QIO. 


You can also use this function to perform bitmap-to-bitmap transfers 
by specifying a source and target location in the TPB and omitting the 
processor buffer. 


QDSS-Specific QIO Interface 
Release Hold 


Release Hold 


Releases all viewports from the hold state. 





FORMAT SYS$QIO_[efn] ,chan, IO$_SETMODE ,fiosb] ,[astadr] 
,fastprm] ,p1 [,p2] [,P3] [,p4] £5] [,pé] 





UNIQUE P1—IO$C_QD_NOHOLD (required) 
PARAMETERS This function code identifies the action the QIO performs. 


P2, P3, P4, P5, P6—Must be 0 





DESCRIPTION The Release Hold QIO function releases viewports from the hold state. 


A viewport is put into the hold state when the Hold Viewport Activity QIO 
- is issued. All viewports except the systemwide viewport are affected by a 
Hold Viewport Activity QIO. 


The driver maintains a count of the number of hold requests. When the 
number of release hold requests equals the number of hold requests, the 
driver releases the screen. 
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QDSS-Specific QIO Interface 


Resume Viewport Activity 


Resume Viewport Activity 
| Resumes activity in a previously suspended viewport. 
FORMAT SYS$QIO_ [efn] ,chan, [|O$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p1 ,p2 [,p3] [,P4] [, 5] [, p6] 





UNIQUE P1—IO$C_QD_RESUME_VP (required) 
PARAMETERS This function code identifies the action the QIO performs. 





P2—Viewport_id (required) 
This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during viewport creation. 


P3, P4, P5, P6—Must be 0 





DESCRIPTION This function resumes activity on a viewport that was previously suspended 
. with the Suspend Viewport Activity QIO function. 
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QDSS-Specific QIO Interface 
Set Color Characteristics 


Set Color Characteristics 


Identifies a system as either color or intensity based. 





FORMAT 


SYS$QIO_[efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p1 ,p2 [,p3] [,P4] [,P5] [, P6] 





UNIQUE 
PARAMETERS 


P1—IO$C_QD_COLOR_CHAR (required) 


This function code identifies the action the QIO performs. 


P2—System flag (required) 


This longword indicates whether the system is color or intensity based: 
¢ 0—Color (RGB) 


e 1—Intensity (monochrome) 


P3, P4, P5, P6é—Must be 0 





DESCRIPTION 


This function identifies a system as either color or intensity based. Your 
application must use this call to inform the driver which type of color 
system it is using. Once this function is specified, the driver accepts only 
Set Color Map Entries QIO requests that match this setting and rejects all 
other Set Color Map Entries QIOs. 
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QDSS-Specific QIO Interface - 
Set Color Map Entries 


Set Color Map Entries’ 


Defines (or alters) the color map. 





FORMAT 


SYS$QIO_ [efn] ,chan ,IO$_SETMODE , [iosb] ,[astadr] 
,[astprm] ,p1 ,p2 ,p3 ,p4 ,p5 [, p6] 





UNIQUE 
PARAMETERS 
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P1—lIO$C_QD_SET_COLOR (required) 


This function code identifies the action the QIO performs. 


To modify the QIO action, ‘‘OR’’ the IO$¢C_QD_SET_COLOR function 
code with one of the following optional function modifiers: 


Function Modifier ~ Action 


lIO$M_QD_INTENSITY A map entry is added on an intensity system. 


lIO$¢M_QD_RESERVED_COLORS The starting color map entry (P4) is interpreted 
as the lO$¢C_QD_TWO_COLOR_CURSOR (set 
two-color cursor) parameter. The buffer must 
contain two map entries of data: two words for 
intensity systems, six words for color systems. 


P2—Address of the color buffer (required) 


P4—Must be 17 
The color buffer differs depending on the system: 


¢ Color system—The buffer must have an ‘’RGB triple’ for each map 
entry you set. An ‘RGB triple’ contains three word-long values: one 
for red, one for green, and one for blue. For five color map entries, the 
color buffer must be 15 words long. 


e Intensity system—The buffer must have a single word-long value for 
each map entry you set. For five color map entries, the color buffer 
must be five words long. 


Only the eight most significant bits are used for color definition. 


P3—Color buffer length, in bytes (required) 
This longword contains the length of the color buffer, in bytes. The 
multiple to use depends on the system: 


¢ Color—6 
e Intensity—2 
P4—Starting color map entry (must be 1) 


This longword contains the color map index to use for the first RGB or 
intensity value specified in the buffer. 


V4.i—June 1989 


QDSS-Specific QIO Interface 
Set Color Map Entries 


P6—Must be 0 


ee ae aaa aR I a eT a NY 

DESCRIPTION This function enables an application to define or alter the color map. Color 
map information is stored in the QDB. You can access the QDB by issuing 
the Get System Information QIO. See Appendix B for a full description of 
the QDB. 
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QDSS-Specific QIO Interface 
Start Request Queue 


Start Request Queue 


Starts the processing of any packets on the request queue. 





FORMAT SYS$QIO_[efn] ,chan , IO$_SETMODE , [iosb] ,[astadr] 
| ,[astorm] ,p1 ,p2 [,p3] [,P4] [,P5] [, P§] 





UNIQUE P1—lIO$C_QD_START (required) 
PARAMETERS This function code identifies the action the QIO performs. 


P2—Viewport_id (required) 
This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during the creation of the viewport. 


P3, P4, P5, P6—Must be 0 





DESCRIPTION This function starts (or restarts) the processing of packets on the request 
queue of the specified viewport. Typically, an application makes this 
call after the queue has been stopped with the Stop Request Queue QIO 
function or after initial viewport creation. 
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QDSS-Specific QIO Interface 
Stop Request Queue 


Stop Request Queue 


Stops the processing of any packets on the request queue. 





FORMAT SYS$QIO_ [efn] ,chan, IO$_SETMODE , [iosb] , [astadr] 
,[astprm] ,pT ,p2 [,p3] [,P4] [,P5] [, 6] 


UNIQUE P1—IO$C_QD_STOP (required) 
PARAMETERS This function code identifies the action the QIO performs. 


P2—Viewport_id (required) 
This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during the creation of the viewport. 


P3, P4, P5, P6—Must be 0 








DESCRIPTION _ The Stop Request Queue QIO stops all processing on the request queue of 
the specified viewport to give the calling process complete control over the 
viewport bitmap. Stopping a viewport request queue ensures that no other 
processes can modify the bitmap of the stopped viewport. 


A viewport management task typically uses this function when changing the 
position of any viewport in the system (using the Set Viewport Region QIO 
function). An application can also use it to freeze the screen for printing 
displayed data. 


Once the Stop Request Queue QIO is invoked, no further commands can 
be executed from the request queue unless the request queue is explicitly 
restarted with the Start Request Queue QIO. 


A Stop Request Queue QIO differs from a Suspend Viewport Activity QIO 
in that it waits for currently processing DOPs to complete before returning 
control. 
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QDSS-Specific QIO Interface 
Suspend Occluded Viewport Activity 


Suspend Occluded Viewport Activity 


Suspends all operations to a specified (occluded) viewport when certain 
operations are requested. 








FORMAT SYS$QIO_[efn] ,chan ,IO$_SENSEMODE , [iosb] 
| ,[astadr] ,[astprm] ,p1 ,p2 [,P3] [, p4] [,P5] 
[pef 
UNIQUE P1—IO$C_QD_OCCLUDED_SUSPEND (required) 


PARAMETERS This function code identifies the action the QIO performs. 
P2—Viewport_id (required) 


This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during the creation of the viewport. 


P3, P4, P5, P6—Must be 0 





DESCRIPTION The Suspend Occluded Viewport Activity QIO suspends operations to an 
occluded viewport when a DOP that the driver cannot process is executed. 


Operations the driver cannot perform on occluded viewports are typically 
Scroll, Move Area, and Move/Rotate operations in which the source is not 
a bitmap ID. 


The application must handle the operation then issue a Resume Viewport 
Activity QIO to continue request queue processing. You can handle the 
operation in the associated AST. The address of the DOP is returned in the 
second longword of the IOSB block. For example, if a Scroll is attempted 
on an occluded viewport, the driver detects the condition and fires the 
AST associated with Suspend Occluded Viewport Activity QIO. The AST 
uses the DOP address returned in the IOSB to determine what action to 
take and issues a Resume Viewport Activity QIO for the viewport when it 
completes. 
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QDSS-Specific QIO Interface 
Suspend Viewport Activity 


Suspend Viewport Activity 


Suspends activity in a specified viewport. 





FORMAT 


SYS$QIO_[efn] ,chan, |O$_SETMODE , [iosb] , [astadr] 
,[astoprm] ,p1 ,p2 [,P3] [,e4] [,P5] Le] 





UNIQUE 
PARAMETERS 


P1—IO$C_QD_SUSPEND_VP (required) 


This function code identifies the action the QIO performs. 


P2—Viewport_id (required) | 
This parameter is the ID of the targeted viewport. The Get Viewport ID 
QIO returns the viewport ID during the creation of the viewport. 


-P3, P4, P5, P6é—Must be 0 





DESCRIPTION 


This function suspends all activity on a specified viewport. Use this call 
to synchronize drawing operations. When any necessary operations are 
completed, you can resume activity on the viewport by calling the Resume 
Viewport Activity QIO function. 


A Suspend Viewport Activity QIO differs from a Stop Request Queue QIO 
in that it does not wait for currently processing DOPs to complete before 
returning control. 
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QDSS-Specific QIO Interface 


Write Bitmap 


Write Bitmap 


Writes data from a user-specified buffer in VAX memory to a bitmap in 
video memory and performs bitmap-to-bitmap transfers. 





FORMAT 


SYSS$QIO_[efn] ,chan ,IO$_QDWRITE , [iosb] ,[astadr] 
,[astprm] ,p7 ,p2 ,[p3] ,p4 ,p5 [, p6] 





UNIQUE 
PARAMETERS 
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P1—Buffer address (required) 

This parameter is the buffer address in VAX memory from which the 
bitmap is written. This buffer must be large enough to hold the bitmap 
specified in the transfer parameter block (P4). In a bitmap-to-bitmap 
transfer, specify a zero in this parameter. 


P2—Buffer length (required) 
This longword contains the length of the buffer specified in P1, in bytes. 


P3—Must be 0 


P4—Transfer parameter block 
This parameter is the transfer parameter block (TPB) that describes the 
bitmap to be written into video memory. The TPB contains: 


e¢ Coordinates for the lower left corner of the bitmap 
e Height and width of the bitmap 
¢ Predefined constant indicating the type of transfer 


¢ For bitmap-to-bitmap transfer, the coordinates for the lower left corner 
of the target bitmap : 


The following diagram shows the data structure that specifies transfer 
parameters. 


The following list describes the contents of each field in the Transfer 
Parameter block. 


QDSS-Specific QIO Interface 
Write Bitmap 


Field Use 


TPB$B_TYPE Type of transfer being performed, either processor- 
to-bitmap (PTB) or bitmap-to-bitmap (BTB). Use the 
constants defined later to load this field. 


TPB$B_SIZE Reserved to Digital 

TPBSW_X_SOURCE X coordinate of lower left corner of source bitmap 
TPB$W_Y_SOURCE Y coordinate of lower left corner of source bitmap 
TPB$W_WIDTH Width of source bitmap 

TPB$W_HEIGHT Height of source bitmap 

TPB$W_X_TARGET X coordinate of lower left corner of target bitmap 

(Only specified for bitmap-to-bitmap transfer) 

TPB$W_Y_TARGET Y coordinate of lower left corner of target bitmap 


(Only specified for bitmap-to-bitmap transfer) 
TPBSW_X_TARGET_VEC1 Reserved to Digital 
TPB$W_Y_TARGET_VECt Reserved to Digital 
TPB$W_L_TARGET_VEC1 Reserved to Digital 
TPBS$W_X_TARGET_VEC2 Reserved to Digital 
TPB$W_Y_TARGET_VEC2 Reserved to Digital 
TPBSW_L_TARGET_VEC2 Reserved to Digital 


The following table defines the constants in conjunction with the TPB. 


Constant Value 


TPB$C_BITMAP_XFR Bitmap-to-bitmap transfer 

TPB$C_SOURCE_ONLY BTP or PTB transfer 

TPB$C_SOURCE_LENGTH Structure length for BTP or PTB transfers 

TPB$C_BITMAP_XFR_LENGTH Structure length for a bitmap-to-bitmap 
transfer 

TPB$C_LENGTH Full length of TPB structure 

P5—TPB length 


This longword contains the length of the transfer parameter block specified 
in P4, in bytes. 


P6—Must be 0 





DESCRIPTION 


This function writes data from a specified buffer in VAX memory to QDSS 
video memory. This QIO transfers all available planes of memory at once. 
If this operation is to affect more than one viewport, it must be preceded 
by a Stop Request Queue QIO. 


An application can also use this function to perform bitmap-to-bitmap 
transfers in a bitmap-to-bitmap transfer, specifying a source and target 
location in the TPB and omitting the processor buffer. 
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5 Using Drawing Operation Primitives 


This chapter includes the following topics: 


Overview of drawing primitives (DOPs) 
Drawing operations with DOPs 
Window management operations with DOPs 


UISDC interface features to use when implementing DOPs 





5.1 Overview of DOPs 


Drawing operation primitives (DOPs) are data structures created by your 
application that contain information the QDSS hardware uses to perform 
drawing operations on the screen. Some DOPs are also used to perform 
window management tasks; for example, to suspend and resume request 
queue activity on a specific viewport. 


DOPs provide a fast and simple way of performing basic drawing and 
window management operations. Use DOPs to perform the following 
drawing operations: 


Draw a simple line, a complex line, a series of lines, or a polygon 
Draw a point, or a series of points 

Draw a filled polygon using a bitmap pattern 

Fill points using an associated bitmap pattern 

Move a rectangular area within a viewport 

Move, rotate, and scale a rectangular area within a viewport 
Scroll a rectangular area 

Draw fixed-width text to the screen 


Draw variable-width text to the screen 


Use DOPs to perform the following window management operations: 


Stop removing entries from a window request queue 
Start removing entries from a stopped request queue 
Suspend drawing operations to a window 


Resume drawing operations in a window 


To perform a drawing operation, your application must complete the 
following steps: 


1 
2 


Allocate storage for the DOP 
Define the structure of the DOP 
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3 Initialize any relevant fields of the DOP structure 
4 Execute the DOP 


How you structure and initialize DOPs depends on which operation you 
perform. 


How you allocate and execute DOPs also depends on whether your 
application uses the UIS windowing environment or provides its own 
windowing services. If an application uses the UIS environment, it can use 
the UISDC routines described in Section 5.3 to allocate and execute DOPs. 
If an application does not use the UIS environment, it must allocate and 
execute DOPs itself, as described in Section 5.4. 


Sections 5.2 through 5.5 provide general information about DOPs that 
you must understand before you attempt to implement any individual 
operation. Section 5.6 describes how to structure and initialize DOPs 
for each type of operation. A FORTRAN example accompanies the 
explanation of each operation in the section. 





5.2 DOP Structure 


This section provides a general description of DOP structure. Section 5.6 
gives a complete description of how to structure DOPs. 


Each DOP structure consists of three substructures (blocks): 


¢ Common block—This fixed-size block begins all DOP structures. It 
contains information that all DOPs require—for example, the ifem_type 
field that identifies which operation the DOP performs and the opcount 
field that indicates how many times the operation should be repeated, 


¢ Unique block—This fixed-size block follows the Common block in all 
DOPs. It contains information more specific to a single operation, or 
group of operations, and its fields and their contents vary accordingly. 
Some operations do not use the fields in this block and others use only 
some of the fields (see the operation-by-operation structure description 
in Section 5.6 for details) but regardless of use, the DOP structure must 
be padded with the entire Unique block. 


¢ Variable block—This variable-length block contains operation-specific 
variables (coordinates, line lengths, and so on). The size of this block 
depends on the number of times an operation is repeated. Thus, if you 
specify a draw-line operation with an opcount of 1, the Variable block 
contains the coordinates needed to draw one line. If you specify an 
opcount of 3, the Variable block must hold the coordinates needed to 
draw three lines. 


Section 5.6 contains an illustration of the Common block and a full 
explanation of each field in the block. The section also contains 
illustrations and explanations of the specific Unique and Variable blocks 
used to define DOPs for each type of operation. 





5.3 Implementing DOPs in the UIS Environment 


If your application runs in the UIS environment, you can use UISDC 
routines to allocate and execute DOPs. 
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5.3.1. Allocating Storage for DOPs in the UIS Environment 


The UISDC$ALLOCATE_DOP routine allocates memory for the DOP 
and initializes some fields of the Common block to default values. 
UISDC$ALLOCATE_DOP has the following format: 


dop_address = UISDCSALLOCATE_DOP (wd_id, size, atb) 
Where: 


dop_address Returned address of the DOP, used in subsequent routines to 
execute the DOP. 


wd_id Window identifier you specify that associates the DOP with a 
window by loading the window-related fields of the Common block 
(the window dimensions and the clipping rectangle). The window 
identifier is returned to an application at viewport creation time. 


size Size, in bytes. This argument is read/write: on input, you specify 
the space for the Variable block; on output, the system returns 
the actual size allocated for the Variable block. The size allocated 
may be smaller than the size you request. Always use the returned 
size in subsequent operations. 


atb Address of an attribute block used to initialize the color, writing- 
mode, and writing-mask fields of the Common block. 


A full routine description of the UISDCSALLOCATE_DOP routine appears 
in Section 5.7. 


Example 5-1 is a FORTRAN program segment that creates a window and 
allocates a DOP to draw 50 points. Note that the input size argument 

is calculated by multiplying the number of times the DOP repeats 

the operation (the opcount) by the predefined constant for the length 

of a single-operation Variable block DOP_POINTS$C_LENGTH. The 
SYS$LIBRARY:VWSSYSDEF file defines a constant for the length of a 
single-operation Variable block for each operation. Section 5.5.4.1 contains 
information about predefined data structures. 


Example 5-1 Allocating a DOP 





! Create a display and window 


VD_ID = UISSCREATE DISPLAY (0.0,0.0, ! lower left corner 

2 50.0,50.0, ! upper right corner 

2 15.0,15.0) ! width & height 

WD_ID = UISSCREATE_WINDOW (VD_ID, ! display ID 

2 'SYSSWORKSTATION’, ! device name 

2 ‘DOP Drawing Window’ ) ! window banner 


! Allocate the DOP 


SIZE = (50 * DOP_POINTSS$C_LENGTH) ! variable block 
DOP = UISDCSALLOCATE_DOP (WD_ID, ! window ID 

2 SIZB, ! size, in bytes 

2 0) { default ATB number 


| NS EES ZF REBT SE BOF SPC ETP PSA PAA SP PPT APES A TP 7 PE EA Ef SS SE PETE 
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5.3.1.1 


§.3.1.2 


Allocation Mechanism 
To allocate DOPs, the system uses a mechanism that provides for efficient 
use of storage as follows: | 


e If possible, it allocates a small amount of storage. 
e After DOP execution, it reuses the storage formerly occupied by DOPs. 


¢ When too much storage is allocated, it waits for free memory. 


By default, DOPs are allocated in two sizes: 

e 128 bytes (small) 

¢ 786 bytes (large) 

You can also set DOP size and available number (see Section 5.3.1.2). 
When you specify the size of the variable portion of the DOP to allocate, 


the system determines whether it can allocate a small DOP, which it does 
if it can. Otherwise, it allocates a large DOP. 


The system also reuses any storage occupied by an already-executed DOP. 
Once a DOP is executed, the system performs the following operations: 


¢ Removes the DOP from the request queue (see Section 5.3.1.2) 


¢ Puts the DOP on a return queue, which is a data structure that points 
to a linked list of previously executed DOPs (the DOP Common block 
provides forward and backward links). 


Each viewport is associated with two return queues: one for small 
DOPs and one for large DOPs. The viewport ID is an address that 
points to a data structure that holds both associated return queues. 


When you use UISDC$ALLOCATE_DOP to allocate a DOP, the system 
completes the following steps: 


1 Checks whether a small or large DOP is required 
2 Attempts to reuse any previously executed DOPs of the same size 


3 If there are no such DOPs, allocates a DOP from system memory or 
waits until a DOP is free for reuse 


Modifying DOP Size and Number 

The available default sizes and numbers of DOPs follow: 
¢ 300 small DOPs, each 128 bytes long 

e¢ 150 large DOPs, each 768 bytes long 


Use these values or alter them to suit your needs. If you want to change 
these values, do so before you attempt any other processing. That is, you 
cannot start with DOPs of one size then change the size and continue. 


You can modify the default sizes of the small and large DOPs within the 
following restrictions: 


e Small DOPs—128-512, inclusive 
e Large DOPs—768-16384, inclusive 
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You can also modify the number of available DOPs, as long as you maintain 
a minimum of 110 small or large DOPs. 


Note that the default DOP setup allocates 300 pages of P1 address space 
for DOPs. If your modifications to size and number of DOPs result in the 
need for more than 300 pages, take the following steps: 


1 Increase the logical value UIS$P1_POOL_SIZE by the increased size in 
bytes. 


2 Increase the SYSGEN parameter, CTLPAGES by the increased size in 
pages. 


To modify the size and number of DOPs, redefine the following logical 
values, as appropriate. 


Table 5-1 Redefinition of Logical Values 


Logical Default 
UIS$SMALL_DOP_SIZE 128 
UIS$LARGE_DOP_SIZE 768 
UIS$NUMBER_OF_SMALL_ 300 
DOPS 

UIS$NUMBER_OF_LARGE_ 150 
DOPS 


5.3.2 Executing DOPs in the UIS Environment 


Once you have defined, allocated, and initialized a DOP, you can execute 
it, with one of three options: 


1 Use the UISDC$EXECUTE_DOP_SYNCH routine to execute the DOP 
synchronously. 


2 Use the UISDC$EXECUTE_DOP_ASYNCH routine to execute the DOP 
asynchronously with completion notification. | 


3 Use the UISDC$QUEUE_DOP routine to execute the DOP 
asynchronously without completion notification. 


The two types of asynchronous execution differ in that the 
UISDC$EXECUTE_DOP_ASYNCH routine takes an I/O status block 
(IOSB) your application can use to check for completion notification. 
UISDC$QUEUE_DOP queues the DOP for execution but provides no way 
to tell when the operation is completed (it is more efficient). Complete 
descriptions of these routines and their arguments appear in Section 5.7. 


PERFORMANCE NOTE: The UISDC$QUEUE_DOP routine is much more efficient than the other 
routines; use it whenever an option exists. 


The FORTRAN program segment in Example 5-2 defines and initializes a 
DOP using a subroutine (the recommended method for FORTRAN) and 
queues a DOP for asynchronous execution without completion notification. 
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Example 5-2 Queuing a DOP for Execution 


{ Allocate the DOP 


! Call subroutine to initialize DOP 


CALL SUB_STRUCTURE (%VAL(DOP), ! address of DOP 
%VAL(DOP+DOP$C_LENGTH)) ! address of a variable 
! block 
! Queue the DOP asynchronously 
CALL UISDCSQUEUE_DOP (WD_ID, ! window ID 
2 %VAL( DOP) ) ! DOP address, by value 
§.3.2.3 Execution Mechanism 


To execute DOPS, you use a mechanism called a request queue. Each 
viewport is associated with a request queue, which is a linked list of any 
DOPs submitted to a viewport for execution. Viewport IDs (including 

the systemwide viewport ID) are addresses that point to the request 
queue structure associated with the viewport. The request queue structure 
contains the starting address of the linked list of DOPs. Each DOP contains 
forward and backward links (in its Common block) to other DOPs in the 
list. These links are updated by the system when a DOP is submitted or 
executed. . 


When you execute a DOP, you must provide the above-mentioned routines 
with the window ID of the viewport where you want to execute the DOP 
(returned in the UIS$CREATE_WINDOW call) and the address of the DOP 
(returned by UISDC$ALLOCATE_DOP). These arguments provide the 
system with the information needed to associate the DOP with the correct 
request queue. 





5.4 Implementing DOPs in a Non-UIS Environment 


If your application does not use the UIS windowing system (for example, 
if it provides its own windowing system), it must allocate and execute 
DOPs itself. Section 5.4.1 describes how an application allocates storage 
for DOPs. Section 5.4.2 describes how an application inserts DOPs on the 
request queue for execution. 


5.4.1. Allocating Storage for DOPS in a Non-UIS Environment 
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Before you allocate new storage for a DOP, check the associated return 
queue to determine if any reusable storage is available there. Use the 
viewport ID to access the return queue (the address of the DOP Queue 
structure where the return queue resides). See Appendix B for a full 
description of the data structure. 


Two return queues are associated with each viewport: 

e One for large DOPs 

e One for small DOPs 

DOP size depends on the amount of information required to describe the 


requested drawing operations fully. Use the MACRO REMQUE instruction 
to remove a DOP from the return queue. 
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If no reusable storage exists, use the LIBS$GET_VM routine to allocate 


storage. 


Example 5-3 creates a viewport, then allocates a DOP by first checking the 


return queue. 


Example 5-3 Allocating a DOP 


PROGRAM DELETE_VIEWPORT 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ‘’VWSSYSDEF’ 
INCLUDE ‘ ($IODEF)’ 


INTEGER*2 CHAN_VP1 


! Declare URD 
INTEGER*2 URD1_VP1(6) 


! Load URD1_VP1 buffer 


URD1I_VP1(1) = 0 ! lower left corner 
URD1_VP1({2) = 0 

URD1_VP1(3) = 99 ! upper right corner 
URD1_VP1(4) = 99 

URD1_VP1(5) = 10 ! absolute coordinate base 
URD1_VP1(6) = 10 


! Define and start VP1 
CALL VIEWPORT (URD1_VP1, CHAN_VP1, VP1_ID) 


! Get a Draw Lines DOP for VP1 
SIZE = (4 * DOP_LINESC_LENGTH) ! calculate size 
CALL GET_DOP (VP1_ID, SIZE, DOP1) 


KEKKKKKKKKKKKKKKKKKKKEK 


q 

! * Get DOP Subroutine * 

! KKKKKKKKKKKRKRKKKKRKRKRKREK 

SUBROUTINE GET _DOP (VIEWPORT_ID, SIZE, DOP) 
IMPLICIT INTEGER* 4(A~Z) 


! Declare external MACRO routine 
EXTERNAL DOPSREMQUE 


DOP = DOPSREMQUE (VIEWPORT_ID, 
2 SIZE) 


Example 5-3 Cont’d. on next page 
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! If none on return queue, calculate size and allocate one. 


IF (DOP .EQ. 0) THEN 
CALL TEST_SIZE (%VAL(VIEWPORT_ID), 
2 SIZE) 
! Allocate appropriate size DOP 
CALL LIBS$GET_VM (SIZE, 
2 DOP) 
END IF 


RETURN 
END 


KEKKKKKEKEKKEKKKKKKKKRKEKEK 


t 
! * TEST SIZE SUBROUTINE * 
PFI IIR RII RIK KK IKI 


SUBROUTINE TEST_SIZE (REQ,SIZE) 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE ‘'VWSSYSDEF’ 


! Associate the predefined structure w/ REQ 


RECORD /REQ_STRUCTURE/ REQ 


IF (SIZE .GT. REQ.REQSW_SMALL_DOP_SIZE) THEN 


SIZE = REQ.REQSW_LARGE DOP_SIZE 
ELSE 

SIZE = REQ.REQSW_SMALL_DOP_SIZE 
END IF 


RETURN 
END 


Separate MACRO Module 


=e Ne Ne 


-title rem_que - does a remque 


SDOPDEF 
$SREQDEF 


viewport ID > return Q 





Example 5-3 Cont'd. on next page 
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p++ 
dopSremque - remove a DOP from the return queues and return it 


descriptions: 

This routine will return a DOP or zero if none is 
available. The size is used to determine whether to use a large 
or small DOP. Note: that it is possible that the size is larger 
than the DOP returned, if this is the case then the application 
must break the request down into smaller chunks and use several 
large DOPs. 


Calling sequence: 
DOP = DOPSREMQUE(VIEWPORT_ID,SIZE) 


Outputs: 
DOP = ZERO if no DOPS available on the queue 


se Se Ne Se we “Oe Se “Oe Ne Ne we NO Ne WO NO NO 


-entry dopSremque,0 


movl @4(ap),rl get req address 


; 
cmpw @8(ap),reqSw_small_dop_size(r1) ; check for small or large DOP 
bgtr 10$ 7 
remque @req$l_return_flink(r1),r0 ; try to get a DOP 
bvs 90$ ¢ nope then clear rO and return 
ret 
? 
; We need a large DOP 
; 
10S: remque @req$L_return_large_flink(R1),r0; get a large DOP 
bvs 90S ; none of these then return 
ret : all set then return 


Can’t get the DOP we want 


\O we we we 


OS: elrl ro 
ret 
.end 


signal error (return zero) 


~e 





Executing a DOP in a Non-UIS Environment 


To execute a DOP in a non-UIS environment, you must insert the DOP on 
the request queue. To insert a DOP on the request queue, use the MACRO 
INSQUE instruction. Use the viewport ID to access the request queue 
(the address of the DOP Queue structure where the return queue resides). 
Appendix B describes the data structure. 


Example 5-4 illustrates viewport creation, DOP allocation, loading the DOP 
with the necessary information, and DOP insertion on the request queue. 





Structuring and Initializing DOPs 


Each DOP structure consists of three blocks—Common block, Unique 
block, and Variable block. Common block fields are the same across 
operations; Unique and Variable block fields vary, depending on the 
operation. 
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Example 5-4 Inserting a DOP on the Request Queue 





! Declare external MACRO routine 
EXTERNAL DOPSINSQUE 


! Define and start VP1 
CALL VIEWPORT (URD1_VP1, CHAN_VP1, VP1_ID) 


! Get a Draw Lines DOP for VPI 
SIZE = (4 * DOP_LINESC_LENGTH) ! calculate size 
CALL GET _DOP (VP1_ID, SIZE, DOP1) 


! Call the draw lines subroutine for a border 


CALL D_LINES (%VAL(DOP1), ! DOP address, by value 
2 %VAL(DOP1+DOPSC_LENGTH), ! var. block address 

2 SIZE) ! DOP size 

! Queue the DOP by calling a MACRO subroutine 

CALL DOPSINSQUE (%VAL(DOP1), ! DOP address, by value 

2 VP1_ID) ! viewport ID 


Separate MACRO Module 


=e Ne we 


etitle ins_que - does an insque tail 


SDOPDEF 
$REQDEF 
++ : 
dopSinsque - inserts a DOP at the tail of the return queue 


calling sequence: 
CALL DOPSINSQUE(DOP,VIEWPORT_ID) 


OUTPUTS: 
NONE 
-entry dopSinsque, 0 
movl 4(ap),xr0 
movl @8(ap),ri 
insque (R0O),@req$L_request_blink(R1) 
movl #1,r0 : indicate success 
ret 


se se we Ne Ve eNO Me NO NO 


-end 








5.5.1. Common Block 


The Common Block is a fixed-size block that begins all DOP structures. It 
contains a number of fields (described completely in the Common Block 
DOP Structure section), but two fields particularly affect the subsequent 
structure of the DOP: 


e¢ The item_type field 


e The operation count opcount field 


5-10 V4.1—June 1989 


Item Type Field 


Using Drawing Operation Primitives 


The item_type field determines which operation the DOP performs and 
therefore affects which Unique and Variable blocks to specify. You must 
explicitly specify the item type with a predefined constant (defined in 
SYS$LIBRARY:VWSSYSDEF). Table 5-2 lists and describes the symbolic 
constants used to specify all possible drawing operations. 


Table 5-2 Symbolic Constants 


Constant 
DOP$C_DRAW_LINES 


DOP$C_DRAW_COMPLEX_ 
LINE 


DOP$C_DRAW_POINTS 
DOP$C_FILL_POLYGON 
DOP$C_FILL_POINT 
DOP$C_FILL_LINES. 


DOP$C_DRAW_FIXED_ 
TEXT 


DOP$C_DRAW_VAR_TEXT 


DOP$C_MOVE_ROTATE_ 
AREA 


DOP$C_MOVE_AREA | 
DOP$C_SCROLL_AREA 


DOP$C_STOP 


DOP$C_START 


DOP$C_DELETE_BITMAP 
DOP$C_SUSPEND 


DOP$C_RESUME 


Opcount Field 


Operation 
Draws lines or polygon. 


Draws a complex patterned line with a sloped length 
and width. Also draws a filled polygon. 


Draws points. 

Draws a filled polygon with a specified pattern. 
Fills a point with a specified pattern. 

Fills a line with a specified pattern. 

Draws text with a specified fixed-space font. 


Draws text with a specified variable-spaced font. 
Moves an area with specified rotation and scaling. 


Moves an area within a viewport. 


Moves area in a viewport. Fills the vacated area 
with background color. 


Stops removing entries from the request queue 
(used when manipulating the screen to handle 
occlusion). 


Starts removing entries from the specified request 
queue. This request can only be made from the 
system viewport. 


Deletes an offscreen bitmap. 


Stops removing DOPs from the request queue until 
the queue is resumed. 


Resumes processing DOPs on the specified queue. 
This request can be made only from the system 
viewport. 


The opcount field indicates how many times the operation should be 


repeated. That is, if the specified item_type is dop$c_draw_lines and the 
opcount is 4, the DOP draws four lines. This field affects the structure of 
the DOP because the size of the Variable block varies with the number 

of operations (more coordinates are necessary to perform the additional 
operations). 
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5.5.2 Unique Block 


5.5.3 Variable Block 


This fixed-size block contains information specific to a single operation or 
group of operations; its fields and their contents vary accordingly. Whether 
or not it uses the fields in the block, every DOP structure must include the 
Unique block. That is, if a particular operation uses only three words of 
the Unique block, the Unique block of the DOP structure must be padded 
to its full length. 


Section 5.6 illustrates and explains the fields in the Unique block 
appropriate for each operation. 


This variable-sized block contains operation-specific variables such as 
coordinates and line lengths. Block size depends on the number of DOP 
operations. In other words, if you specify a draw-line operation with an 
opcount of one, the Variable block contains coordinates needed to draw one 
line. If you specify an opcount of three, the Variable block holds coordinates 
needed to draw three lines (and be three times as long). 


Section 5.6 illustrates and explains the fields in the Variable block needed 
for a single occurrence of each operation. It also lists the predefined 
constant for the length of a one-operation Variable block. Use this constant 
to calculate the input size argument of the UISDCS$ALLOCATE_DOP 
routine. Multiply the constant by the number of times the DOP is to repeat 
the operation (the opcount). 


5.5.4 Programming Considerations 


When you program an application that performs drawing operations, you 
can implement the DOP structure in various ways. Depending on the 
programming language and the exact nature of the operation, you can use 
one of these options: 


e Use the predefined structure provided in the 
SYSLIBRARY:VWSSYSDEF file 


e Define the full DOP structure using your language structured-type 
statements 


If you use the predefined DOP structure, you do not have to construct the 
DOP explicitly in your application. However, it is not always possible to 
use the predefined structure. 


5.5.4.1 
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The Predefined DOP Structure 
SYSLIBRARY:VWSSYSDEF lan (where lan is the file extension for your 
programming language) contains a DOP definition file. 


VWSSYSDEF defines DOP-related constants, including offset values that 
define each field in the DOP structure. You can use these predefined 
offsets in your application to initialize the DOP fields. The system allocates 
the DOP storage; you must associate a structure with the storage to initialize 
the proper fields. The offsets provide a way of accessing fields within the 
structure. Section 5.6 labels each field in the DOP illustrations with its 
predefined offset. 


For example, VWSSYSDEF defines an offset DOP$W_ITEM_TYPE that 
identifies the location of the item_type field in the DOP. Once you associate 
the returned storage with a structure, you can use the offset to reference 
the structure. 


In each module where you reference it, you must “‘include”’ or “‘insert’’ 
the VWSSYSDEF file to use any predefined constants and offsets. Become 
familiar with the way the VWSSYSDEF file defines the DOP structure for 
your programming language. 


Initializing fields with the offsets is straightforward with regard to the fixed 
portion of the DOP (the Common and Unique blocks) and somewhat 
more complex with regard to the Variable block. The VWSSYSDEF file 
defines offsets for only one occurrence of an operation in the Variable 
block from the end of the fixed portion. In other words, to draw a single 
line, the Variable block for a Draw Lines operation requires four fields with 
predefined offsets. To draw two lines, however, the Variable block requires 
eight fields, but only four offsets are predefined. To write to the second set of 
fields, use the same offsets but change the point from which they are offset. 


In languages such as PASCAL that support arrays of structures, you can 
define an array of Variable block structures and increment the original 
offset by the length of a ‘‘one-operation” Variable block. The VWSSYSDEF 
file provides constants for both the offset and Variable block length. The 
original offset (the end of the fixed portion) is DOP$C_LENGTH, and the 
constants for the “‘one-operation”’ Variable block lengths are listed with the 
respective operation in Section 5.6. 


In a language such as FORTRAN that does not support arrays of structures, 
you have two options: 


¢ Completely define the structure of the Variable block using a 
STRUCTURE statement. 


e Define a structure the size of a one-operation Variable block, then use 
a loop that increments the offset to initialize the DOP for a series of 
operations. 


For a one-operation case, FORTRAN can use the predefined offsets. 


The examples that accompany the operation descriptions are written in 
FORTRAN. Section 5.5.4.2 describes the conventions they follow. 
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Using the Examples | 

The DOP reference section contains FORTRAN examples that are 
subroutines that construct the DOP structure and initialize necessary 
fields. To eliminate redundancy, the calling program is removed from each 
example. For the sake of illustration, Example 5-5 contains a sample calling 
program. The sample calling program performs the following functions: 


Creates a display and window. 


Allocates storage for a DOP that draws a box (four lines—opcount 
equals four). 


Passes the returned DOP address to a subroutine that defines and 
initializes the DOP structure. (This must be done in FORTRAN to 
avoid reallocating storage during the structure declaration—other high- 
level languages can avoid the subroutine call by using a pointer to 
associate the structure with the allocated storage.) 


Passes the address of the Variable block (length of the fixed portion of 
the DOP plus the DOP address). 


Queues the DOP for execution. 


Hibernates the process (so the result can be viewed). 


NOTE: The examples assume that the application is using the UIS/UISDC 
interface. 
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Example 5-5 Calling Program for Example Subroutines 





PROGRAM DRAW_LINES 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE 'UISENTRY’ 
INCLUDE ‘VWSSYSDEF’ 


! Create a display and window 


VD_ID = UISS$CREATE_DISPLAY (0.0,0.0, ! lower left corner 

2 50.0,50.0, ! upper right corner 

2 15.0,15.0) ! width & height 

WD_ID = UISSCREATE_WINDOW (VD_ID, ! display ID 

2 'SYSSWORKSTATION’, ! device name 

2 . ‘DOP Drawing Window’ ) ! window banner 


! Allocate the DOP 

SIZE = (4 * DOP_LINES$C_LENGTH) 

DOP = UISDCSALLOCATE_DOP (WD_ID, ! window ID 

2 SIZE, ! variable portion size, in bytes 
2 0) ! default ATB number 


! Call the subroutine 
CALL SUB_STRUCTURE (%VAL(DOP), ! DOP address 
%VAL(DOP+DOPS$C_LENGTH))! Var. block address 


{ Queue the DOP asynchronously 
CALL UISDCSQUEUE_DOP (WD_ID, ! window ID 
2 %VAL( DOP) ) ! DOP address, by value 


CALL SYSS$HIBER( ) 
END 


NOTE: FORTRAN requires you pass the DOP address that UISDC_$ALLOCATE 
returns by value to a subroutine. The subroutine associates the address 
with a record structure using the RECORD statement. If this is not done 
in a subroutine, the RECORD statement allocates storage redundantly for 
the DOP. 


5.6 The DOP Reference 


This section provides an easy reference for structuring DOPs. It contains 
the following illustrations and descriptions: 





e Illustration and detailed description of the the Common block structure 


e Illustration and detailed description of the Unique and Variable block 
structure for each operation 


e Description of how to perform each operation 


¢ Program example of how to perform each operation 


First the Common block is described, then each operation is described 
and listed in alphabetical order. The running head reflects which DOP is 
described on a page. 


Each block is accompanied by the record name associated with the block 
in the SYS$LIBRARY:VWSSYSDEF definition file. Each field lists the 
predefined field name. These names can be used to reference the DOPs. 


NOTE: The descriptions assume that an application is using the UIS/UISDC 
interface to allocate and execute DOPs and load bitmaps. You can perform 
these functions without using the UIS/UISDC interface. 
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Common Block 


All DOP structures must begin with the Common block. 





common block 
(dop_structure) 


Field Description 

DOP$L_FLINK DOP queue forward link, the address of the preceding DOP in the request queue 

DOP$L_BLINK DOP queue backward link, the address of the subsequent DOP in the request 
queue 

DOP$W_SIZE DOP size in bytes 

DOP$B_TYPE DOP structure type 

DOP$B_SUB_TYPE Reserved for use by Digital 

DOP$L_DEC_RESERVED Reserved for use by Digital 

DOP$L_DEC_ Reserved for use by Digital 

RESERVED2 

DOP$L_USER_ Reserved for use by the user 

RESERVED 

DOP$W_FLAGS These are defined within DOP$W_FLAGS: 
DOP$V_DELETE_ This field is 1 bit long, and starts at bit 0. When this 
BITMAP field equals 1, the offscreen source bitmap (identified in 

the bitmap_ID field) is deleted at operation completion. 

DOP$V_SYSTEM_ This field is 1 bit long and starts at bit 1. When this 
DOP field equals 1, the DOP is returned to the system return 


queue when the drawing operation is completed. A 
window manager specifies this when it needs to draw in 
the systemwide viewport or when it allocates a system 
DOP to draw on a user viewport. 


DOP$V_NO_RETURN This field is 1 bit long and starts at bit 2. When this 
field equals 1, the DOP is not returned to the return 
queue when the drawing operation is completed and is 
not deleted. This is useful in cases where an application 
wishes to preserve information in the DOP, possibly in 
the user-reserved field. 


DOP$W_OPCOUNT Number of drawing operations requested by this packet. For example, if the 
drawing operation you request is ‘‘draw points,”’ this field indicates how many 
points should be drawn (using coordinates in the variable portion of the DOP). 
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Field 


Description 





DOP$W_ITEM_TYPE 


DOP$W_MODE 
DOP$L_MASK 
DOP$L_SOURCE_INDEX 
DOP$L_FCOLOR 
DOP$L_BCOLOR 
DOP$L_BITMAP_ID 


DOP$L_BITMAP_ 
GLYPHS 


DOP$W_VP_MAX_X 
DOP$W_VP_MAX_Y 
DOP$W_DELTA_X 
DOP$W_DELTA_Y 
DOP$W_VP_MIN_X 


DOP$W_VP_MIN_Y 


Type of drawing operation requested by DOP. Symbolic constants used to specify 
all possible drawing operations follow: 


DOP$C_DRAW_LINES 
DOP$C_DRAW_COMPLEX_LINE 
DOP$C_DRAW_POINTS 
DOP$C_FILL_POLYGON 
DOP$C_FILL_POINT 
DOP$C_FILL_LINES 
DOP$C_DRAW_FIXED_TEXT 
DOP$C_DRAW_VAR_TEXT 
DOP$C_MOVE_ROTATE_AREA 
DOP$C_MOVE_AREA 
DOP$C_SCROLL_AREA 
DOP$C_STOP 

DOP$C_START 
DOP$C_DELETE_BITMAP 
DOP$C_SUSPEND 
DOP$C_RESUME 


Writing mode code as expected by QDSS. There are 16 different writing modes 
that you can specify using constants listed in Appendix C. 


The plane mask. This field should be -1 to be compatible with previous versions 
of VAX Workstation Software. 


Source index. Used with the writing mode to determine the result of overlaid 
colors. (See the Description section.) 


Foreground color index. This is an index into the color map that is used for the 
foreground (or writing) color. 


Background color index. This is an index into the color map that is used for the 
background color. 


ID bitmap. Used to identify bitmaps in text images, pattern fill, and delete bitmap 
operations. This value is 0 if the operation is not related to bitmaps. 


Bitmap backing store address. If a stored bitmap is paged out of the bitmap 
storage area, the address where it is stored in VAX memory is loaded into this 
field. 


Viewport relative device coordinate maximum X. Used to determine the upper right 
corner of the viewport. 


Viewport relative device coordinate maximum Y. Used to determine the upper right 
corner of the viewport. 


Delta from the lower left corner of the viewport to the lower left corner of the 
clipping rectangle (the actual writing area). 


Delta from the lower left corner of the viewport to the lower left corner of the 
clipping rectangle (the actual writing area). 


Viewport relative device coordinate minimum X. Used to determine the lower left 
corner of the viewport. 


Viewport relative device coordinate minimum Y. Used to determine the lower left 
corner of the viewport. 
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DESCRIPTION = The Common Block is a fixed-size block that must begin all DOP structures. 
A number of the fields in this block must be loaded in every DOP, while 
other fields in the block are important only to specific types of operations 
(for example, color operations and bitmap operations). 
Required Fields | 


The fields you must explicitly load depend on whether your application is 
running in the UIS environment. 


If your application is not running in the UIS environment, it must load all 
relevant fields of the Common Block. That is, during allocation, the system 
loads all fields needed for the DOP except for the first six fields. 


If your application runs in the UIS environment, some of the Common Block 
fields that must be initialized are actually loaded by UISDC$ALLOCATE_ 
DOP after it allocates storage for the DOP (default initialization); others 
must be explicitly initialized by your application (explicit initialization). The 
following sections list the fields in these two categories. 


Default Initialization 


Using the attribute block the application specifies in the routine call, 
UISDC$ALLOCATE_DOP initializes the following fields: 


e Writing mode 

e Foreground and background colors 

e Viewport minimum and maximum coordinates 

e Clipping rectangle delta coordinates 

You might affect any of these fields by modifying the ATB before allocation 
or by overriding initialization directly after allocation. 


The ALLOCATE routine initializes the following fields, which are used for 
the DOP execution mechanism: 


e =6Forward link 


e = Backward link 


e Size 
e Type 
¢ Sub_type 


You can access these fields, but do not attempt to modify them. 
Explicit Initialization 
Your application must explicitly initialize the following fields: 


¢ item_type—Identifies which operation the DOP performs. To initialize 
this field, specify one of the symbolic constants listed above. 
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¢ opcount—Tells how many times the operation should be repeated. If 
you specify a Draw Lines operation with an opcount of 1, one line is 
drawn. If you specify an opcount of 3, three lines are drawn. This field 
is directly related to the Variable block of a DOP. The Variable block 
contains the coordinates needed to draw a line (in this example). To 
draw three lines, the Variable block must hold the coordinates needed 
to draw three lines (and be three times as long). 


Color Fields 

Use the following fields in the Common block to manipulate color: 

¢ Foreground color index 

¢ Background color index 

¢ Writing mode 

e Source index 

The foreground color index and background color index determine the color to 
use for writing to the foreground and background, respectively. Modifying 


the index changes the color on a per-operation basis. That is, DOPs can 
write in different colors to the same viewport. 


Writing mode determines how writing operations use foreground and 
background colors to display graphic objects (for example, whether objects 
overlay one another on the screen or negate each other). The 16 writing 
modes are described in Appendix C. 


The source index is a number used to determine the color interaction of 
objects being written to the screen with objects already existing on the 
screen. The source index involves the following interactions: 


e State of the pixels in existing bitmap 

e Specified source index value 

¢ Specified writing mode 

e Specified foreground and background colors. 

e The use_mask modifier of the writing mode (if specified) 

e Specified source bitmap (if bitmap_id field is specified) 

Figure 5-1 demonstrates how the source index works. (This figure does 
not specify the source bitmap or the use_mask writing mode modifier.) 

It illustrates two intersecting circles: Circle A has a foreground index of 
010 (binary—like all numbers in this example) and a background index 
of 100 (remember, the indexes represent colors in the color map—for 
simplicity, only three bits are used to represent pixel settings). Circle B has 
a foreground index of 001 and a background index of 100. The specified 


source index value is 001, and the specified writing mode is WRIT$DSO 
(destination ORed with source). 
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Figure 5-1 How the Source Index Works 


Circle A Circle B 
FG = 010 FG = 001 
BG = 100 BG = 100 





Drawn using 101 as color map index 


Source Index = 001 
MLO-1069-87 


When you write objects to the screen, the system performs a logical 
operation on the present contents of the screen bitmap and the source 
index. The logical operation is determined by the specified writing mode. 
Because the DSO mode is specified in Figure 5-1, Circle A foreground 
index 010 is ORed with the source index, 001, resulting in the number 011. 


The system uses the following procedure to determine which color map 
index to use for writing: 


e If the bit position in the resulting number includes a 1, the system 
checks the corresponding bit position in the foreground index and sets 
or clears the bit to agree with the foreground index. 


e If the bit position in the resulting number includes a 0, the system 
checks the corresponding bit position in the background index and sets 
or clears the bit to agree with the background index. 


In Figure 5-1, the number that results from the logical operation is 101, so 
the intersecting portion of the circles is written in the color represented by 
101 in the color map. 


Determining the Result of Screen Intersections 


When you specify a bitmap (DOP$L_BITMAP_ID is non-zero) and the 
use_mask_2 writing mode modifier, this process is more complicated. The 
following steps describe how to determine the result of any intersection on 
the screen. The sole objective is to overlay a character on top of an existing 
display. (In Figure 5-1, steps 2 and 5 are not meaningful because these 
options are not specified.) | 


STEP 1 
bitmap_index if oy. 
as (source_bitmap exists AND source_bitmap = 0) 
THEN 
0 
ELSE 


source_index 
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If you use the bitmap ID to specify a bitmap for the DOP, the driver 
creates a bitmap index by inserting the source index in any bitmap bit 
position where there is a 1. The source_bitmap is 1 bit; the resulting bitmap_ 
index reflects the number of planes of color used. 


STEP 2 
mask = IF 
use_mask 
THEN 
bitmap_index 
ELSE 


—1 


If you specify the use_mask modifier as part of the writing mode, the 
bitmap_index is used as the mask. 


STEP 3 
IF 
fg_bg_ 
selector = use_mask 
THEN 
(data) logical operation source_index 
ELSE 


bitmap_index 


To obtain the foreground and background selector, perform a logical 
operation (determined by the specified writing mode) on the data on the 
screen and either the source_index value (if use_mask was specified) or the 
bitmap_index. 


STEP 4 
t= (fg AND fg_bg_selector) 
(og AND (NOT fg_bg_selector)) 


The value of the foreground-and-background selector determines which 
bits are set to foreground and background colors—fg and bg refer to the 
foreground and background colors specified in the DOP. (t1 is the data 
output to screen when no mask is specified.) 


STEP 5 
final_data = (t1 AND mask) 
- ¥ OR 
(data AND (NOT(mask))) 


Use the mask and t1 to determine the data output to the screen. 


Bitmap Fields 


Two fields in the Common Block are used with bitmap operations: the 
bitmap_ID field and the bitmap_glyphs field. (Bitmap operations can be text 
or fill-pattern.) 


An operation that uses a bitmap must first load the bitmap from processor 
memory into offscreen bitmap memory with the UISDC$LOAD_BITMAP 
routine. That routine returns a bitmap_ID that identifies the loaded bitmap 
in offscreen memory. 
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To use that bitmap in a bitmap-related DOP, you must initialize the bitmap_ 
ID field with the returned ID. For example, once you have loaded a bitmap 
and initialized the bitmap_ID field of a Fill Polygon DOP, the DOP uses the 
bitmap pattern to fill the polygon it creates. 


The bitmap_glyphs field enables the system to retrieve the bitmap that is 
not available in offscreen memory. The bitmap_glyph is the address (in 
processor memory) where the bitmap is stored. If a DOP requires the 
bitmap, it is swapped back in. 


NOTE: The bitmap_glyph address must remain valid and not be reused until a 
Delete Bitmap DOP has been executed and that DOP has completed. 


Miscellaneous Fields 


The writing mode field specified in a DOP affects the way the drawing 
operations appear on the screen. On a QDSS system, the screen is more 
than one bit deep. Some operations (such as Move Area) might require a 
writing mode other than the default to operate properly. 


By setting bits in the flags field, you can perform the following operations: 


e¢ Delete the bitmap specified in the bitmap_ID field, typically for a ‘‘one- 
shot’’ bitmap DOP. The DOP is performed, then the bitmap is deleted 
from offscreen memory. 


e Not return a DOP for reuse, typically done for a ‘‘one-shot’’ DOP. 
This step prevents information contained in the DOP from being 
overwritten. 


e Return the DOP storage to the systemwide return queue. This step is 
done when a DOP is allocated from the systemwide viewport and 
inserted on another viewport request queue. 


Examples 


The examples in the operation-specific sections show how to initialize the 
Common Block for each drawing operation. 


Initializing the Variable Block 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both the X and Y source coordinates. 
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Delete Bitmap 


unique block 


variable block 


The Delete Bitmap operation permits you to delete a bitmap specified in 
the bitmap_ID field of the Common block. 





The Unique block is not relevant to this operation. 





The Variable block is not relevant to this operation. 





DESCRIPTION 


Since this is a queued operation, make sure that bitmap glyphs maintained 
by the application remain valid until Delete Bitmap has been executed. 


Relevant Common Block Fields 


Specify the bitmap ID of the bitmap you want to delete in the Common 
block. 7 


Initializing the Variable Block 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify a for both the X and Y source coordinates. 
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Draw Complex Line 


The Draw Complex Line operation enables you to draw a line or patterned 
line of variable width with a slope in both the length and width direction. 





unique block The Unique block is not relevant to this operation. 





variable block 
(dop_move_r_array) 


Field Use 
DOP_MOVE_RS$W_FILLER This field is reserved for use by DIGITAL. 
DOP_MOVE_R$W_X_SOURCE If a bitmap_ID is specified in the Common 


block, this field is the X offset into the line 
style bitmap; otherwise, it is ignored. 


DOP_MOVE_R$W_Y_SOURCE lf a bitmap_ID is specified in the Common 
block, this field is Y offset into the line style 
bitmap; otherwise, it is ignored. 

DOP_MOVE_R$W_WIDTH If a bitmap_ID is specified in the Common 
block, this field is the width of the line style 
bitmap to be used; otherwise, it is ignored. 


DOP_MOVE_R$W_HEIGHT If a bitmap_ID is specified in the Common 


block, this field is the height of the line style 
bitmap to be used; otherwise, it is ignored. 


DOP_MOVE_R$W_X_TARGET X coordinate of the starting point of the line. 
DOP_MOVE_R$W_Y_TARGET Y coordinate of the starting point of the line. 
DOP_MOVE_R$W_X_TARGET_ Delta of the X coordinate starting point and 
VEC1 end point of vector 1. 
DOP_MOVE_R$W_Y_TARGET_ Delta of Y coordinate starting point and end 
VEC1 point of vector 1. 
DOP_MOVE_R$W_L_TARGET_ This field is irrelevant to this operation. 
VEC1 
DOP_MOVE_R$W_X_TARGET_ Delta of the X coordinate starting point and 
VEC2 end point of vector 2. 
DOP_MOVE_R$W_Y_TARGET_ Delta of Y coordinate starting point and end 
VEC2 point of vector 2. 
DOP_MOVE_R$W_L_TARGET_ This field is irrelevant to this operation. 
VEC2 





DESCRIPTION The Draw Complex Line operation enables you to draw a line or variable 
width patterned line with a slope in both the length and width direction. 
Refer to the description of the Draw Line DOP (which also draws lines) to 
see which routine is appropriate for the operation you want to perform. 
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Relevant Common Block Fields 


You can specify a bitmap ID in the Common block to indicate a line style 
for a complex line. Use the x_source and y_source fields of the Variable block 
to specify an offset into the bitmap as a starting point for the line style and 
use the width and height fields to specify the extents of the bitmap to use. 


By default, the system uses a fill pattern of all ones. 


Initializing the Variable Block 


To draw a complex line, specify a starting point and two vectors. Vector_ 

1 indicates the length of the line and the slope of the length. Vector_2 
indicates the width of the line and the slope of the width. Specify a delta X 
and Y value for each vector relative to the target X and Y. To determine the 
proper X and Y values for the vectors, subtract the X and Y values of the 
endpoint from those of the starting point to determine a delta value. 


The length fields are ignored in this operation. 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both the X and Y source coordinates. 


PERFORMANCE NOTE: Lines are drawn faster if Vector_1 specifies a slope of less than 45 


degrees. 





EXAMPLE 


- 


The following FORTRAN program draws a complex line to the screen as 
follows: 


1 Creates a bitmap pattern 

2 Uses UISDC$LOAD_BITMAP to load the bitmap 
3 Specifies an opcount of 1 
4 


Initializes the Variable block with the offset and extent of the specified 
bitmap pattern 


on 


Initializes the Variable block with a starting position of (50,50) 


6 Initializes the Variable block with the deltas of the length and width 
endpoint coordinates 


Calling program 


. 
PKK KERR KK KEK KEKE KIKI E KKK RK 


* BITMAP FUNCTION * 


PRK KKK KERKKKKKKK KKK KK 


INTEGER*4 FUNCTION GET_BITMAP ID ! window ID 
! Declare the storage 

IMPLICIT INTEGER* 4 (A-Z) 

COMMON /WINDOW/ WD_ID, VD_ID 

INTEGER*4 BITMAP _ID 

INTEGER*2 BITMAP(16) 
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! Load the bitmap values 


BITMAP(1) = ‘AAAA’X 
BITMAP(2) = '5555’X 
BITMAP(3) = ‘AAAA’X 
BITMAP(4) = '5555’X 
BITMAP(S) = ‘AAAA’X 
BITMAP(6) = '5555'X 
BITMAP(7) = ’AAAA’X 
BITMAP(8) = '5555’X 
BITMAP(9) = ‘AAAA’X 
BITMAP(10) = '5555’X 
BITMAP(11) = ‘AAAA’X 
BITMAP(12) = ’5555’X 
BITMAP(13) = ’AAAA’X 
BITMAP(14) = '5555’X 
BITMAP(15) = ’AAAA’X 
BITMAP(16) = '5555'X 


! Load the bitmap from buffer to QDSS memory 
BITMAP_ID = UISDCSLOAD_BITMAP (WD_ID, window ID 


! 
2 BITMAP, ! bitmap address 
2 32, ! bitmap length (bytes) 
2 16, ! bitmap width, in pixels 
2 1) ! bits/pixel 


GET_BITMAP_ID = BITMAP_ID 
END ! function 


PII IRR RIK KR RRR RRR IR EK 
! * COMPLEX LINES SUBROUTINE * 


YP RARE REIKI KEKEKKKEKEKEKKKKIE KK 


SUBROUTINE SUB_COMPLEX_LINE (DOP, DOP_VAR) 
INCLUDE ‘'VWSSYSDEF’ 


! Declare the GET_BITMAP_ID function 
INTEGER*4 GET_BITMAP_ID 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Associate the predefined variable structure w/ DOP_VAR 
RECORD /DOP_MOVE_R_ARRAY/ DOP_VAR 


! Load the values 

DOP.DOPS$W_ITEM_TYPE = DOPSC_DRAW_COMPLEX_LINE 

DOP. DOPSW_OP_COUNT = 1 

DOP.DOPS$L_BITMAP_ID = GET BITMAP_ID() ! function call 


DOP_VAR.DOP_MOVE_RS$W_X_SOURCE = 0 
DOP_VAR.DOP_MOVE_RSW_Y_SOURCE = 0 
DOP_VAR.DOP_MOVE_RS$W_WIDTH = 10 
DOP_VAR.DOP_MOVE_RSW_HEIGHT = 10 
DOP_VAR.DOP_MOVE_RS$W_X_TARGET = 50 
DOP_VAR.DOP_MOVE_R$W_Y_TARGET = 50 
DOP_VAR.DOP_MOVE_RSW_X_TARGET_VEC1 = 300 
DOP_VAR.DOP_MOVE_RS$W_Y_TARGET_VEC1 = 300 
DOP_VAR.DOP_MOVE_RSW_X_TARGET_VEC2 = -20 
DOP_VAR.DOP_MOVE_RS$W_Y_TARGET_VEC2 = -30 


RETURN 
END 
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Draw Fixed Text 


unique block 
(text_args) 


variable block 
(dop_ftext_array) 


This operation describes the additional DOP structure needed to draw 


‘fixed-width text to the screen. 














Field Use 

DOP$W_TEXT_HEIGHT Height of each character, in pixels. This value is 
constant for each font. 

DOP$W_TEXT_WIDTH Width of each character. 

DOP$W_TEXT_STARTING_ The viewport relative X coordinate for the starting 

x position of the text on the screen. 

DOP$W_TEXT_STARTING_ The viewport relative Y coordinate for the starting 

Y position of the text on the screen. 

Field Use 


DOP_FTEXT$W_OFFSET_X  X coordinate of the offset into the font where a 
specific character is located. 


DOP_FTEXT$W_OFFSET_Y _Y coordinate of the offset into the font where a 
specific character is located. 


Variable-Length Constant: dop_ftext$c_length 





DESCRIPTION 


The Draw Fixed Text operation enables you to write fixed-width text to 
the screen. To draw scaled, rotated, or differently spaced text, use the 
Move/Rotate DOP. 


Relevant Common Block Fields 


To draw fixed-width text to the screen, first load a bitmap that contains a 
fixed-width font from processor memory to the offscreen bitmap memory. 
Use the UISDC$LOAD_BITMAP routine to load a bitmap. This routine 
returns a bitmap ID that must be loaded in the bitmap_ID field of the 
Common block. (Section 5.7 describes loading bitmaps with the UISDC 
interface.) 


Initializing the Unique Block 


The Unique block describes the height and width of the specified font and 
the position to start writing on the screen. You must initialize all these 
fields. When you write text, you specify the starting point as the upper left 
corner of the first character (provided the character height is specified as a 
positive number). 
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Initializing the Variable Block 


The Variable block specifies an offset into the font to indicate which 
character to write. 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both the X and Y source coordinates. 





EXAMPLE 
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a pp wOnD = 


The following FORTRAN program writes two characters of text to the 
screen as follows steps: 


Creates a two-letter bitmap—H I (using a function) 

Uses UISDC$LOAD_BITMAP to load the bitmap 

Specifies an opcount of 2 

Initializes the Unique block with a starting position of (100,100) 
Initializes the Variable block with the offsets of the two characters 
Note that the specified offset values seem to write the letters in reverse 


order because of the way VAX memory loads the bitmap: the I is loaded at 
(0,0). 


! Calling program 


! Function that 
! and loads the 


defines 
bitmap (font) 


INTEGER*4 FUNCTION GET_BITMAP_ID ! window ID 


! Declare the storage 
IMPLICIT INTEGER*4(A~Z) 


COMMON /WINDOW/ 


WD_ID, VD_ID 


INTEGER*4 BITMAP_ID 
INTEGER*2 BITMAP(16) 


! Load the bitmap values 


BITMAP(1) = '423E’X 
BITMAP(2) = ’4208'X 
BITMAP(3) = '4208'X 
BITMAP(4) = '4208’X 
BITMAP(5) = '7E08’X 
BITMAP(6) = '4208'X 
BITMAP(7) = '4208'X 
BITMAP(8) = '423E’X 


! Load the bitmap from buffer to QDSSs memory 


BITMAP_ID = UISDCSLOAD_BITMAP (WD_ID, 


- 


window ID 


Z BITMAP, ! bitmap address 

2 32, _.! bitmap length (bytes) 

2 16, ! bitmap width, in pixels 
2 1) ! bits/pixel 
GET_BITMAP_ID = BITMAP_ID 

END ! function 


L RHKKKKKKKK 


! Subroutine that draws the text 


| KERR KEK 


SUBROUTINE FIXED_TEXT (DOP, DOP_VAR) 


IMPLICIT INTEGER*4(A-Z) 

INCLUDE /VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET_BITMAP_ID 


! Associate the predefined structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


t Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 


INTEGER*2 OFFSET_X1 
INTEGER*2 OFFSET_Y1 


INTEGER*2 OFFSET_X2 
INTEGER*2 OFFSET _Y2 


END STRUCTURE ! Variable block 


! Associate the structure with the DOP 
RECORD /VARIABLE_BLOCK/ DOP_VAR 


{ Load the values 

DOP.DOPS$W_ITEM_TYPE = DOPS$C_DRAW_FIXED_TEXT 

DOP. DOPSW_OP_COUNT = 2 

DOP.DOPS$L_BITMAP_ID = GET_BITMAP_ID() ! function call 


DOP.DOP$W_TEXT_HEIGHT = 8 
DOP.DOP$W_TEXT_WIDTH = 8 

DOP. DOP$W_TEXT_STARTING_X 
DOP.DOPS$W_TEXT_STARTING_Y 


100 
100 


DOP_VAR.OFFSET_X1 
DOP_VAR.OFFSET_Y1 


! reversed in memory 


8 
0 
DOP_VAR.OFFSET_X2 = 0 
DOP_VAR.OFFSET_Y2 10) 


tt 


RETURN 
END 


DOP Structures 
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Draw Lines 


This operation describes the additional structure needed to draw lines with 
specified end points. 





unique block 


(plot_args) 
Field Use 
DOP$W_PLOT_FILL_WIDTH If a bitmap_ID is specified in the Common block, 


this field is the width of the line style bitmap. 
Otherwise, it is ignored. 


DOP$W_PLOT_FILL_HEIGHT lf a bitmap_ID is specified in the Common block, 
this field is the height of the line style bitmap. 
Otherwise, it is ignored. 


DOP$W_PLOT_FILL_ If a bitmap_ID is specified in the Common block, 

PATTERN_X this field is the X offset into the line style bitmap. 
Otherwise, it is ignored. 

DOP$W_PLOT_FILL_ if a bitmap_ID is specified in the Common block, 

PATTERN_Y this field is the X offset into the line style bitmap. 


Otherwise, it is ignored. 





variable block 
(dop_line_array) 





Field Use 

DOP_LINE$W_X1 X coordinate of the starting point of the line 
DOP_LINESW_Y1 Y coordinate of the starting point of the line 
DOP_LINESW_X2 X coordinate of the end point of the line 
DOP_LINE$W_Y2 Y coordinate of the end point of the line 


Variable-Length Constant: dop_line$c_length 


DESCRIPTION The Draw Lines operation enables you to draw the following structures: 
e Aline 
e 6A series of lines 


e A polygon (a series of connected lines) 


Draw Lines differs from Fill Lines in that it begins drawing at the specified 
starting point with the bitmap offset specified (if specified). Fill Lines 
begins drawing at the specified starting point revealing the repeated fill 
pattern relative to the lower left corner of the screen. 


The width of lines drawn with this operation is always one pixel. The last 
pixel of each line is not drawn. 
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Relevant Common Block Fields 


You can specify a bitmap ID in the Common block to indicate a line style 
to be used when drawing a line. If you do, use the fill_pattern_x and fill_ 
pattern_y fields of the Unique block to specify an offset into the bitmap as a 
starting point for the line style and use the width and Hest fields to specify 
the extents of the bitmap to use. 


By default, the system uses a fill pattern of all ones. 


Initializing the Unique Block 


If you specify a bitmap in the Common block, you must specify the bitmap 
offset and extents in the Unique block. If you do not specify a bitmap, the 
Unique block is ignored by a Draw Lines operation. 


Initializing the Variable Block 


To draw a line, specify its two end points in the Variable block of the DOP 
structure. To draw a series of lines (or a polygon), specify the end points 
of all the lines in the Variable block and specify the number of lines you 
want to draw in the opcount field of the Common block. 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both the X and Y source coordinates. 





EXAMPLE This FORTRAN program performs the following steps to draw a polygon: 


1 Uses the predefined structure to initialize the fixed portion of the DOP 
to write four lines 


2 Defines and initializes the Variable portion of the DOP to hold the end 
point coordinates of four connecting lines 


{ Calling program 


SUBROUTINE D_LINES (DOP, DOP_VAR) 
INCLUDE ‘’VWSSYSDEF’ 


! Associate the predefined structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 


INTEGER*2 FIRST_LINE_X1 
INTEGER*2 FIRST_LINE_Y1 
INTEGER*2 FIRST_LINE_X2 
INTEGER*2 FIRST_LINE_Y2 


INTEGER*2 SECOND_LINE_X1 
INTEGER*2 SECOND_LINE_Y1 
INTEGER*2 SECOND _LINE_X2 
INTEGER*2 SECOND _LINE_Y2 


INTEGER*2 THIRD_LINE_X1 
INTEGER*2 THIRD_LINE_Y1 
INTEGER*2 THIRD_LINE_X2 
INTEGER*2 THIRD_LINE_Y2 
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INTEGER*2 FOURTH_LINE_X1 
INTEGER*2 FOURTH_LINE_Y1 
INTEGER*2 FOURTH_LINE_X2 
INTEGER*2 FOURTH_LINE_Y2 


END STRUCTURE ! dop_structure 


! Associate the structure with the DOP_VAR address 
RECORD /VARIABLE_BLOCK/ DOP_VAR 


! Load the DRAW_LINE values 
DOP.DOPSW_ITEM_TYPE = DOPS$C_DRAW_LINES 
DOP.DOP$W_OP_COUNT = 4 


DOP_VAR.FIRST_LINE_X1 = 50 
DOP_VAR.FIRST_LINE_Y1 = 50 
DOP_VAR.FIRST LINE_X2 = 50 
DOP_VAR.FIRST_LINE_Y2 = 75 


DOP_VAR.SECOND_LINE_X1 = 50 
DOP_VAR.SECOND_LINE_Y1 = 75 
DOP_VAR.SECOND_LINE_X2 = 75 
DOP_VAR.SECOND_LINE_Y2 = 75 


DOP_VAR.THIRD_LINE_X1 = 75 
DOP_VAR.THIRD_LINE_Y1l = 75 
DOP_VAR.THIRD_LINE_X2 = 75 
DOP_VAR.THIRD_LINE_Y2 = 50 


DOP_VAR. FOURTH_LINE_X1 = 75 
DOP_VAR.FOURTH_LINE_Y1 = 50 
DOP_VAR.FOURTH_LINE_X2 = 50 


DOP_VAR.FOURTH_LINE_Y2 = 50 


RETURN 
END 
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Draw Points 


This operation describes the additional DOP structure you need to draw 
points to the screen. 





unique block 
(plot_args) 





Field Use 
DOP$W_PLOT_FILL_ lf a bitmap ID is specified in the Common block, 
WIDTH this field is the width of the bitmap. Otherwise, it is 
ignored. 
DOP$W_PLOT_FILL_ If a bitmap ID is specified in the Common block, 
HEIGHT this field is the height of the bitmap. Otherwise, it is 
ignored. 
DOP$W_PLOT_FILL_ If a bitmap ID is specified in the Common block, this 
PATTERN_X field is the X offset into the bitmap. Otherwise, it is 
ignored. 
DOP$W_PLOT_FILL_ If a bitmap ID is specified in the Common block, this 
PATTERN_Y field is the X offset into the bitmap. Otherwise, it is 
ignored. 
variable block 
(dop_point_array) 
Field Use 
DOP_POINT$W_X X coordinate of the point to draw 
DOP_POINT$W_Y Y coordinate of the point to draw 


Variable-Length Constant: dop_draw_points$c_length 





DESCRIPTION 


The Draw Points operation enables you to draw a point, a series of points, 
or a series of points that correspond to a specified pattern to the screen. 


Relevant Common Block Fields 


If you specify a bitmap ID in the Common block to indicate a pattern to 
use when drawing a point or a series of points, use the following fields: 


e = fill_pattern_x and fill_pattern_y fields of the Variable block—To specify an 
offset into the bitmap as a starting point for the pattern 


¢ width and height fields—To specify the extents of the bitmap 


The pattern is incremented one pixel/point and repeats when the width is 
reached. This operation is useful for drawing a thin patterned curve. 


By default, the system uses a fill pattern of all ones. 


DOP Structures 
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Initializing the Variable Block 


To draw a point, specify the X and Y coordinates of the point in the 
Variable block. To draw a series of points, specify the X and Y coordinates 
of all the points in the Variable block and specify the number of points you 
want to draw in the opcount field of the Common block. 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both the X and Y source coordinates. 


DOP Structures 
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EXAMPLE 


! Calling program 


SUBROUTINE DRAW_POINT (DOP, DOP_VAR) 
INCLUDE ’VWSSYSDEF’ 


{ Associate the predefined structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


{ Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 


INTEGER*2 FIRST_POINT_X 
INTEGER*2 FIRST_POINT_Y 


INTEGER*2 SECOND_POINT_X 
INTEGER*2 SECOND _POINT_Y 


INTEGER*2 THIRD_POINT_X 
INTEGER*2 THIRD_POINT_Y 


END STRUCTURE ! dop_structure 


! Associate the structure with the DOP_VAR address 
RECORD /VARIABLE_BLOCK/ DOP_VAR 


! Load the DRAW_POINT values 
DOP.DOPSW_ITEM_TYPE = DOPSC_DRAW_POINTS 
DOP.DOP$W_OP_COUNT = 3 


DOP_VAR.FIRST_POINT_X = 5 
DOP_VAR.FIRST_POINT_Y = 5 


5 
25 


DOP_VAR.SECOND_POINT_X 
DOP_VAR.SECOND_POINT_Y 


DOP_VAR.THIRD_POINT_X = 25 
DOP_VAR.THIRD_POINT_Y = 25 


RETURN 
END 


The following FORTRAN example draws three points to the screen. 
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Draw Variable Text 


This operation describes the additional DOP structure needed to draw tex 
of variable width to the screen. 





unique block 


(text_args) 
Field Use 
DOP$W_TEXT_HEIGHT Height of each character, in pixels; this value is 
constant for each font 
DOP$W_TEXT_WIDTH Ignored for variable-width fonts 


DOP$W_TEXT_STARTING_X The viewport-relative X coordinate for the starting 
position of the text on the screen 


DOP$W_TEXT_STARTING_Y The viewport-relative Y coordinate for the starting 
position of the text on the screen 





variable block 
(dop_vtext_array) 


Field Use 


DOP_FTEXT$W_OFFSET_X  X coordinate of the offset into the font where a 
specific character is located 


DOP_FTEXT$W_OFFSET_Y _ Y coordinate of the offset into the font where a 
specific character is located 


DOP_VTEXT$W_WIDTH Width of the specified character 


Variable-Length Constant: dop_vtext$c_length 





DESCRIPTION The Draw Variable Text operation enables you to write variable-width text 
to the screen. To draw scaled, rotated, or differently spaced text, use the 
Move/Rotate DOP. 


Relevant Common Block Fields 


To draw variable-width text to the screen, first load a bitmap with a 
variable-width font from processor memory to the offscreen bitmap 
memory. To load a bitmap, use the UISDC$LOAD_BITMAP routine. 
This routine returns a bitmap ID that must be loaded in the bitmap_ID field 
of the Common block for this operation to succeed. (See Section 5.7 for 
details about loading bitmaps.) 


Initializing the Unique Block 


The Unique block describes both the height of the specified font and the 
position to start writing on the screen. The width field is ignored for this 
operation. Note that when you write text, the position you specify as the 
starting point is the upper left corner of the first character (provided the 
character height is specified as a positive number). 
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Initializing the Variable Block 
The Variable block indicates which character to write as follows: 
e Specifies an offset into the font 


¢ Specifies the width of the character 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both the X and Y source coordinates. 


EXAMPLE 


The following FORTRAN program writes three characters of text to the 
screen (the word LIP) by taking the following steps: 


1 Uses a function to creates a 3-letter bitmap—P L I 
Uses UISDC$LOAD_BITMAP to load the bitmap 
Specifies an opcount of 3 


Initializes the Unique block with a starting position of (100,100) 


ao ff W ND 


Initializes the Variable block with the offsets of the three characters (in 
the proper order) and their respective widths © 


Note that because of the way VAX memory loads the bitmap, the specified 
offset values appear reversed: the I is loaded at (0,0). 
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! Calling program 


t Function that defines 
! and loads the bitmap (font) 
INTEGER*4 FUNCTION GET_BITMAP_ID ! window ID 


{ Declare the storage 
IMPLICIT INTEGER*4(A-Z) 
COMMON /WINDOW/ WD_ID, VD_ID 
INTEGER*4 BITMAP_ID 

INTEGER* 2 BITMAP( 16) 


! Load the bitmap values 
BITMAP(1) = '784B’X 


BITMAP(2) = '4844'x 
BITMAP(3) = '4844'°x 
BITMAP(4) = '7844'X 
BITMAP(5) = '0844’X 
BITMAP(6) = '0844’x 
BITMAP(7) = '0844’x 
BITMAP(8) = '09CE’X 


! Load the bitmap from buffer to QDSS memory 


BITMAP_ID = UISDCSLOAD_BITMAP (WD_ID, ! window ID 

2 BITMAP, ! bitmap address 

2 32, ! bitmap length (bytes) 

2 16, { bitmap width, in pixels 
2 1) ! bits/pixel 


GET_BITMAP_ID = BITMAP_ID 
END t function 


L RHKKKEKKKNK 


{ Subroutine that draws the text 
1 KRAKKKKKKKK 


SUBROUTINE VAR_TEXT (DOP, DOP_VAR) 


IMPLICIT INTEGER*4(A-Z) 

INCLUDE ‘'VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET_BITMAP_ID 


! Associate the predefined structure w/ DOP 
RECORD /ROP_STRUCTURE/ DOP 


{ Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 


INTEGER*2 OFFSET_X1 
INTEGER*2 OFFSET_Y1 
INTEGER*2 WIDTH1 


INTEGER*2 OFFSET_X2 
INTEGER*2 OFFSET_Y2 
INTEGER*2 WIDTH2 


INTEGER*2 OFFSET_X3 
INTEGER*2 OFFSET_Y3 
INTEGER*2 WIDTH3 


END STRUCTURE ! Variable block 


! Associate the structure with the DOP 
RECORD /VARIABLE_BLOCK/ DOP_VAR 


! Load the values 

DOP.DOPS$W_ITEM_TYPE = DOP$C_DRAW_VAR_TEXT 

DOP.DOPS$W_OP_COUNT = 3 

DOP.DOP$L_BITMAP_ID = GET_BITMAP_ID() ! function call 


DOP.DOPSW_TEXT_HEIGHT = 8 
DOP. DOP$W_TEXT_STARTING_X 
DOP.DOPS$W_TEXT_STARTING_Y 


5 $ 


i 


DOP_VAR.OFFSET_X1 


DOP_VAR.OFFSET Yl =0 ! 
DOP_VAR.WIDTH1 = 5 
DOP_VAR.OFFSET_ X2 =0 ! 
DOP_VAR.OFFSET_Y2 = 0 
DOP_VAR.WIDTH2 = 5 
DOP_VAR.OFFSET_X3.= 10 ! 


DOP_VAR.OFFSET_Y3 = 0 
DOP_VAR.WIDTH3 = 6 


RETURN 
END 


100 
100 


reversed in memory 
’ L’ 


Lan hd 
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Fill Lines 


This operation describes the additional structure needed to draw lines, 
using a specified bitmap pattern. 





unique block 


(plot_args) 
Field Use 
DOP$W_PLOT_FILL_WIDTH Width of fill pattern (from offscreen bitmap), 
in bits; bitmap is identified in bitmap_ID field 
DOP$W_PLOT_FILL_HEIGHT Height of fill pattern (from offscreen bitmap), 


in bits; bitmap is identified in bitmap_ID field 


DOP$W_PLOT_FILL_PATTERN_X X coordinate in the bitmap from which to 
base the fill pattern; bitmap is identified in 
bitmap_ID field 

DOP$W_PLOT_FILL_PATTERN_Y Y coordinate in the bitmap from which to 
base the fill pattern; bitmap is identified in 
bitmap_ID field 





variable block 
(dop_line_array) 


Field Use 

DOP_LINE$SW_x1 X coordinate of the starting point of the line 
DOP_LINE$W_Y1 Y coordinate of the starting point of the line 
DOP_LINE$W_X2 X coordinate of the end point of the line 
DOP_LINE$W_Y2 Y coordinate of the end point of the line 


Variable-Length Constant: dop_line$c_length 





DESCRIPTION The Fill Lines operation enables you to draw patterned lines by associating 
the lines with a bitmap pattern. Fill Lines differs from Draw Lines in that 
it associates the specified bitmap pattern with the whole screen area and 
“‘reveals’’ the pattern when it draws a line. Draw Lines draws the line, 
using the specified pattern. 


NOTE: This operation is restricted to drawing horizontal lines. This restriction 
might be lifted in a future release. 


Relevant Common Block Fields 


To draw a patterned line to the screen, use the UISDC$LOAD_BITMAP 

routine to load a bitmap with the pattern from processor memory to the 

offscreen bitmap memory. This routine returns a bitmap ID that must be 
loaded in the bitmap_ID field of the Common block for this operation to 

succeed. (See Section 5.7 for details about loading bitmaps.) 
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Initializing the Unique Block 


The Unique block describes the portion of the loaded bitmap pattern used 
to fill the line. 


Initializing the Variable Block 


To draw a line, specify the line end points in the Variable block of the DOP 
structure. To draw a series of lines, specify the end points of all the lines 
in the Variable block and specify the number of lines to draw in the opcount 
field of the Common block. 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both the X and Y source coordinates. 





EXAMPLE This FORTRAN example program draws a filled line as follows: 
1 Uses UISDC$LOAD_BITMAP to load a bitmap pattern 
2 Specifies DOP$C_FILL_LINES in the item_type field 


3 Defines and initializes the Variable portion of the DOP to hold the 
endpoint coordinates of the line 


! Calling program 


! Function that defines 
! and loads the bitmap 
INTEGER*4 FUNCTION GET_BITMAP_ID { window ID 


! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 
COMMON /WINDOW/ WD_ID, VD_ID 
INTEGER*4 BITMAP_ID 
INTEGER*2 BITMAP( 16) 

! Load the bitmap values 


BITMAP(1) = ‘AAAA’X 
BITMAP(2) = '5555’X 
BITMAP(3) = ‘AAAA’X 
BITMAP(4) = '5555’X 
BITMAP(5) = ‘AAAA’X 
BITMAP(6) = '5555’X 
BITMAP(7) = ‘AAAA’X 
BITMAP(8) = '5555'X 
BITMAP(9) = ’AAAA’X 
BITMAP(10) = '5555’X 
BITMAP(11) = ‘AAAA’X 
BITMAP(12) = '5555’X 
BITMAP(13) = ‘AAAA’X 
BITMAP(14) = '5555’X 
BITMAP(15) = ‘AAAA'X 
BITMAP(16) = '5555'X 


! Load the bitmap from buffer to QDSS memory 
BITMAP_ID = UISDCSLOAD_BITMAP (WD_ID, ! window ID 


2 BITMAP, ! bitmap address 

2 32, ! bitmap length (bytes) 

2 16, ! bitmap width, in pixels 
2 1) ! bits/pixel 
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GET_BITMAP_ID = BITMAP_ID 
END ! function 


LR RK 


! Subroutine that draws the line 
L KKKKKEEKER 


SUBROUTINE F_LINE (DOP, DOP_VAR\ 


IMPLICIT INTEGER*4(A-Z) 

INCLUDE ‘VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET _BITMAP_ID 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Associate the predefined variable structure w/ DOP_VAR 
RECORD /DOP_LINE_ARRAY/ DOP_VAR 


! Load the FILL_LINE values 
PARAMETER DOP$C_FILL_LINE = 5 
DOP.DOPSW_ITEM_TYPE = DOPS$C_FILL_LINE 


DOP.DOPSW_OP_COUNT = 1 
DOP.DOP$L_BITMAP_ID = GET_BITMAP_ID{() t function call 


DOP.DOPS$W_PLOT_FILL_WIDTH = 16 
DOP.DOP$W_PLOT_FILL_HEIGHT = 16 
DOP.DOP$W_PLOT_FILL_PATTERN_X = 0 
DOP.DOP$W_PLOT_ FILL _PATTERN_Y = 0 


DOP_VAR.DOP_LINESW_X1 = 50 


DOP_VAR.DOP_LINESW_Y1 = 50 
DOP_VAR.DOP_LINESW_X2 = 150 
DOP_VAR.DOP_LINESW_Y2 = 50 
RETURN 

END 


DOP Structures 
Fill Point 





Fill Point 


unique block 
(plot_args) 


variable block 


This operation describes the additional DOP structure needed to map a 
point to a defined bitmap. 





Field Use 

DOP$W_PLOT_FILL_WIDTH Width of fill pattern (from offscreen bitmap), 
in bits; bitmap is identified in bitmap_I/D field 

DOP$W_PLOT_FILL_HEIGHT Height of fill pattern (from offscreen bitmap), 


in bits; bitmap is identified in bitmap_ID field 
DOP$W_PLOT_FILL_PATTERN_X X coordinate in the bitmap from which to 

base the fill pattern; bitmap is identified in 

bitmap_ID field 
DOP$W_PLOT_FILL_PATTERN_Y Y coordinate in the bitmap from which to 


base the fill pattern; bitmap is identified in 
bitmap_ID field 











(dop_point_array) 

Field Use 

DOP_POINT$W_X X coordinate of the point to fill 

DOP_POINT$W_Y Y coordinate of the point to fill 
DESCRIPTION The Fill Point operation enables you to map individual points you draw to 


the screen to a bitmap pattern you specify. If the corresponding bit in the 
bitmap is set, the point is drawn to the screen (filled); if not, then the point 
is not drawn. 


Relevant Common Block Fields 


To draw patterned points to the screen, first load a bitmap that contains the 
pattern from processor memory to the offscreen bitmap memory. Use the 
UISDC$LOAD_BITMAP routine to load a bitmap. This routine returns a 
bitmap ID that must be loaded in the bitmap_ID field of the Common block 
in order for this operation to succeed. (See Section 5.7 for details about 
loading bitmaps.) 


Initializing the Unique Block 


The Unique block describes which portion of the loaded ie pattern 
should be used to determine whether to fill the point. 
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Initializing the Variable Block 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both X and Y source coordinates. 


EXAMPLE This sample FORTRAN program segment draws 90 points in a patterned 
sine curve as follows: 


a 


of AW N 
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Creates a bitmap pattern (in a function) 

Uses UISDC$LOAD_BITMAP to load the bitmap 
Specifies an opcount of 90 

Initializes the Unique block 


Uses the SIND and REAL functions to calculate the points on the sine 
curve ! 


Initializes the Variable block with the points by indexing into the 
Variable block array 


{ Calling program 


! Function that defines 
! and loads the bitmap 
INTEGER* 4 FUNCTION. GET _BITMAP_ID ! window ID 


! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 
COMMON /WINDOW/ WD_ID, VD_ID 
INTEGER*4 BITMAP_ID 
INTEGER*2 BITMAP(16) 


! Load the bitmap values 


BITMAP(1) = ‘’AAAA’X 
-BITMAP(2) = '5555'X 
BITMAP(3) = ‘AAAA’X 
BITMAP(4) = '5555’X 
BITMAP(5) = 'AAAA’X 
BITMAP(6) = '5555’X 
BITMAP(7) = ‘AAAA’X 
BITMAP(8) = '5555’X 
BITMAP(9) = ‘AAAA’X 
BITMAP(10) = '5555’X 
BITMAP(11) = ’AAAA’X 
BITMAP(12) = '5555'X 
BITMAP(13) = ’AAAA’X 
BITMAP(14) = '5555’X 
BITMAP(15) = ‘AAAA’X 
BITMAP(16) = '5555’X 


! Load the bitmap from buffer to QDSS memory 
BITMAP ID = UISDCS$LOAD_BITMAP (WD_ID, window ID 


4 
2 BITMAP, ! bitmap address 
2 32, ! bitmap length (bytes). 
2 ge MG ! bitmap width, in pixels 
2 1) ! bits/pixel 


GET_BITMAP_ID = BITMAP_ID 
END ! function 


P RRR KKEKEKEKKEEKREEKEKEKKKEEEEK 


! * FILL POINT SUBROUTINE * 


KKK KKKKKEKKKKKKKEKKEKKE KK EE 


SUBROUTINE F_POINT (DOP, DOP_VAR) 


IMPLICIT INTEGER*4(A-Z) 

INCLUDE ‘VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET_BITMAP_ID 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 
INTEGER*2 POINTS (60) 
END STRUCTURE { dop_structure 
! Associate the structure with the DOP_VAR address 
RECORD /VARIABLE_BLOCK/ DOP_VAR 


! Load the DRAW_POINT values 

DOP.DOPSW_ITEM_TYPE = DOPSC_FILL_POINT 
DOP.DOPSW_OP_COUNT = 90 

DOP.DOP$L_BITMAP_ID = GET_BITMAP_ID()  ! function call 
DOP,.DOPSW_PLOT_FILL_WIDTH = 16 
DOP.DOPSW_PLOT_FILL_HEIGHT = 16 
DOP.DOPSW_PLOT_FILL_PATTERN_X = 0 
DOP.DOPSW_PLOT_FILL_PATTERN_Y = 0 


DOP Structures 
Fill Point 
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! Use a loop to load 30 points 
! set counters 

x=1 

X_COORD = 1 

Y_COORD = 2 


DO WHILE (X .LE. 91) 
DOP_VAR. POINTS (X_COORD) 
DOP_VAR.POINTS(Y_COORD) 


X 
SIND(REAL(X)) * 100 


tow 


! Increment counters 

X=xX4+1 

X_COORD = X_COORD + 2 

Y_COORD = Y_COORD + 2 
END DO 


RETURN 
END 


Fill Polygon 


unique block 
(plot_args) 


variable block 
(dop_poly_array) 


DOP Structures 
Fill Polygon 


This operation describes the additional DOP structure to create a polygon 
and fill it with a specified pattern. 





Field 
DOP$W_PLOT_FILL_WIDTH 


DOP$W_PLOT_FILL_HEIGHT 


DOP$W_PLOT_FILL_PATTERN_X 


DOP$W_PLOT_FILL_PATTERN_Y 


Use 


Width of fill pattern (from offscreen bitmap), 
in bits; bitmap is identified in bitmap_ID field. 
If no bitmap is specified, this field is ignored. 


Height of fill pattern (from offscreen bitmap), 
in bits; bitmap is identified in bitmap_ID field. 
If no bitmap is specified, this field is ignored. 


X coordinate in the bitmap from which to 
base the fill pattern; bitmap is identified in 
bitmap_ID field. If no bitmap is specified, 
this field is ignored. 


Y coordinate in the bitmap from which to 
base the fill pattern; bitmap is identified in 
bitmap_ID field. If no bitmap is specified, 
this field is ignored. 





Field 
DOP_POLY$W_LEFT_xX1 


DOP_POLY$W_LEFT_Y1 
DOP_POLY$W_LEFT_X2 
DOP_POLY$W_LEFT_Y2 
DOP_POLY$W_RIGHT_X1 
DOP_POLY$W_RIGHT_Y1 
DOP_POLY$W_RIGHT_X2 


DOP_POLY$W_RIGHT_Y2 


Use 


X coordinate of the starting point of a line that 
defines the left edge of a polygon 


Y coordinate of the starting point of a line that 
defines the left edge of a polygon 


X coordinate of the end point of a line that 
defines the left edge of a polygon 
Y coordinate of the end point of a line that 
defines the left edge of a polygon 


X coordinate of the starting point of a line that 
defines the right edge of a polygon 


Y coordinate of the starting point of a line that 
defines the right edge of a polygon 


X coordinate of the end point of a line that 
defines the right edge of a polygon 


Y coordinate of the end point of a line that 
defines the right edge of a polygon 


Variable-Length Constant: dop_poly$c_length 
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DESCRIPTION The Fill Polygon operation enables you to write a polygon (more precisely, 
a trapezoid) filled with a pattern or a solid color. The trapezoid you create 


must have top and bottom lines that are both parallel and horizontal. That 
is, Y coordinates of the upper corners must be the same, and Y coordinates 
of the lower corners must be the same. 


NOTE: Some of these restrictions might be lifted in a future release. 


Relevant Common Block Fields 


To draw a pattern-filled polygon to the screen, first use the UISDC$LOAD_ 
BITMAP routine to load a bitmap with the desired pattern from processor 
memory to the offscreen bitmap memory. This routine returns a bitmap 
ID that must be loaded in the bitmap_ID field of the Common block. (See 
Section 5.7 for details about loading bitmaps.) 


To fill the polygon with the solid foreground color, specify a bitmap ID of 
0 and omit the Unique block. 


Initializing the Unique Block 


The Unique block describes which portion of the loaded bitmap pattern 
you should use to fill the polygon. 


initializing the Variable Block 


The Variable block describes the polygon (more precisely, the trapezoid) 
by specifying the end points of the two lines (the left and right edges of the 
polygon). Note that the top and bottom lines of the trapezoid must be both 
parallel and horizontal. Therefore, Y coordinates of the upper corners must 
be the same, and Y coordinates of the lower corners must be the same. 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both the X and Y source coordinates. 





EXAMPLE This FORTRAN sample program segment draws a filled polygon as follows: 
1 Creates a bitmap pattern (in a function) 

Uses UISDC$LOAD_BITMAP to load the bitmap 

Specifies an opcount of 1 


Initializes the Unique block 


a fF AW ND 


Initializes the Variable block with the end points of the two sides of the 
polygon 


! Calling program 


! Function that defines 
! and loads the bitmap 


INTEGER*4 FUNCTION GET _BITMAP_ID ! window ID 
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! Declare the storage 
IMPLICIT INTEGER*4(A-Z) 
COMMON /WINDOW/ WD_ID, VD_ID 
INTEGER*4 BITMAP_ID 
INTEGER*2 BITMAP( 16) 


{ Load the bitmap values 
BITMAP(1) = ’AAAA’X 


BITMAP(2) = '5555'X 

BITMAP(3) = ’AAAA’X 

BITMAP(4) = '5555’X 

BITMAP(5) = ‘AAAA’X 

BITMAP(6) = '5555’X 

BITMAP(7) = ‘AAAA’X 

BITMAP(8) = '5555'X 

BITMAP(9) = ‘AAAA’X 

BITMAP(10) = ’5555’X 

BITMAP(11) = ’AAAA’X 

BITMAP(12) = '5555’X 

BITMAP(13) = ‘AAAA’X 

BITMAP(14) = '5555’X 

BITMAP(15) = ‘AAAA’X 

BITMAP(16) = '5555'X 

! Load the bitmap from buffer to QDSS memory 

BITMAP_ID = UISDCSLOAD_BITMAP (WD_ID, ! window ID. 

2 BITMAP, ! bitmap address 
2 32, ! bitmap length (bytes) 
2 16, ! bitmap width, in pixels 
2 1) ! bits/pixel 


GET_BITMAP_ID = BITMAP_ID 
END { function 


f RK KKEE 


! Subroutine that draws the polygon 


f RKKKEKRKKK 


SUBROUTINE F_POLYGON (DOP, DOP_VAR) 


IMPLICIT INTEGER*4(A-Z) 

INCLUDE ’VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET_BITMAP_ID 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Associate the predefined variable structure w/ DOP_VAR 
RECORD /DOP_POLY_ARRAY/ DOP_VAR 


t Load the POLYGON values 
DOP.DOPSW_ITEM_TYPE = DOPSC_FILL_POLYGON 


DOP.DOPSW_OP_COUNT = 1 
DOP.DOP$L_BITMAP_ID = GET_BITMAP_ID() ! function call 


DOP.DOP$W_PLOT_FILL_WIDTH = 16 
DOP.DOP$W_PLOT_FILL HEIGHT = 16 
DOP.DOP$W_PLOT_FILL_PATTERN_X = 0 
DOP.DOP$W_PLOT_FILL_PATTERN_Y = 0 


DOP_VAR.DOP_POLY$W_LEFT_X1 = 
DOP_VAR.DOP_POLYSW_LEFT_Y1 = 10 
DOP_VAR.DOP_POLY$W_LEFT_X2 = 50 
DOP_VAR.DOP_POLY$W_LEFT_Y2 = 100 


I 
rary 
[o) 


DOP_VAR.DOP_POLY$W_RIGHT_X1 = 150 
DOP_VAR.DOP_POLY$W_RIGHT_Y1 = 10 
DOP_VAR.DOP_POLY$W_RIGHT_X2 = 100 
DOP_VAR.DOP_POLYS$W_RIGHT_Y2 = 100 
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RETURN 
END 
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Move Area 


unique block 


variable block 
(dop_move_array) 


This operation describes the additional DOP structure needed to move 
(copy) a rectangular area on the screen from one point to another. 





The Unique block is not relevant to this operation. 











Field | Use 

DOP_MOVE$W_FILLER Reserved for use by DIGITAL 

DOP_MOVE$W_X_SOURCE X coordinate of the lower left corner of the 
source area (area to be moved) 

DOP_MOVE$W_Y_SOURCE Y coordinate of the lower left corner of the 
source area 

DOP_MOVE$W_WIDTH Width of the area to be moved, in pixels 

DOP_MOVE$W_HEIGHT Height of the area to be moved, in pixels 

DOP_MOVE$W_X_T ARGET X coordinate of the lower left corner of the 


target area (the area to which the source 
area is moved) 


DOP_MOVE$W_Y_TARGET Y coordinate of the lower left corner of the 
. . target area 


Variable-Length Constant: dop_move$c_length 


DESCRIPTION 


The Move Area operation enables you to move (copy) a rectangular area 
from one point to another, either on the screen or in offscreen memory. 


Relevant Common Block Fields 


Overlay is the default writing mode loaded into the Common block 
(from the ATB) during allocation. When you are performing a Move 
Area operation, use COPY mode. To load the UIS$S_MODE_COPY value 
into the writing_mode field of the Common block, use the UIS$SET_ 
WRITING_MODE routine to modify the ATB before you allocate, or use 
the predefined offsets to load the field with the value directly. 


WRIT$C_S (source only) is the non-UIS environment writing mode that 
corresponds to COPY. 


Initializing the Variable Block 


To move an area, specify the coordinates that define the lower left corner 
of the rectangle you want to move (source area), the height and width of 

the area, and the coordinates that define the lower left corner of the area 
where you are moving it (target area). 
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EXAMPLE 


The following FORTRAN program draws fixed text to the screen at the 


point (100,100). It then moves (copies) an 8-pixel by 16-pixel rectangle 
containing the text from (100,100) to (50,50). 


In the Move Area DOP, the source rectangle coordinates are (100,93) 
because when text is written to a specified point on the screen (that is, 
100,100) the point is considered the upper left corner of the text—but for 
Move Area you must specify the lower left corner of the rectangle. 


The full calling program is shown to clarify the example. 


PROGRAM MOVE_TEXT 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE 'UISENTRY’ 
INCLUDE ‘UISUSRDEF’ 
INCLUDE ‘VWSSYSDEF’ 
COMMON /WINDOW/ WD_ID, VD_ID 


! Create a display and window 


VD_ID = UISSCREATE_DISPLAY (0.0,0.0, ! 
2 50.0,50.0, ! 
2 15.0,15.0) ! 


lower left corner 
upper right corner 
width & height 


WD_ID = UISSCREATE_WINDOW (VD_ID, ! display ID 
2 ‘SYSSWORKSTATION’, ! device name 
2 ‘DOP Drawing Window’) ! window banner 


! Allocate the DOP for DRAW_LINES 
SIZE = (2 * DOP_FTEXTSC_LENGTH) 


DOP1 = UISDCSALLOCATE_DOP (WD_ID, ! window ID 

2 SIZE, ! variable portion size, in bytes 
2 0) ! default ATB number 

! Call the FIXED_TEXT subroutine 

CALL SUB_FIXED_TEXT (%*VAL(DOP1), 

2 %VAL(DOP1+DOP$C_LENGTH) ) 

! Queue the DOP asynchronously 

CALL UISDCSQUEUE_DOP (WD_ID, ! window ID 

2 %VAL(DOP1) ) ! DOP address, by value 


! Modify the writing mode in ATB 
CALL UISSSET_WRITING MODE (VD_ID, 


2 0, ! default ATB 
2 1, ! modified ATB 
2 UIS$C_MODE_COPY) ! new mode 


! Allocate the DOP for MOVE_AREA 
SIZE = DOP_MOVESC_LENGTH 
DOP2 = 


UISDCSALLOCATE_DOP (WD_ID, ! 
2 SIZE, ! 
2 1) ! 


! Call the MOVE_AREA subroutine 
CALL SUB_MOVE_AREA (%VAL(DOP2), 


window ID 
size, in bytes 


number of modified ATB 


2 %VAL(DOP2+DOP$C_LENGTH) ) 


! Queue the DOP asynchronously 
CALL UISDCSQUEUE_DOP (WD_ID, ! 
2 %VAL(DOP2) ) ! 


CALL SYSSHIBER() 


END 

PIR IRI IOI OR ROR ROR III OI IIR 

! * BITMAP FUNCTION * 
PHIRI IR KIRK ERK KKK 

INTEGER*4 FUNCTION GET_BITMAP_ID ! 
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window ID 


DOP address, by value 


window ID 


! Declare the storage 
IMPLICIT INTEGER* 4 (A-Z) 
COMMON /WINDOW/ WD_ID, VD_ID 
INTEGER*4 BITMAP _ID 
INTEGER*2 BITMAP(16) 


! Load the bitmap values 


BITMAP(1) = ’'423E’X 

BITMAP(2) = '4208’X 

BITMAP(3) = '4208’X 

BITMAP(4) = '4208'X 

BITMAP(5) = '7E08’X 

BITMAP(6) = '4208'X 

BITMAP(7) = '4208’X 

BITMAP(8) = '4208'X 

! Load the bitmap from buffer to QDSS memory 

BITMAP_ID = UISDCSLOAD_BITMAP (WD_ID, =! window ID 

2 BITMAP, ! bitmap address 

2 32, ! bitmap length (bytes) 
2 16, ! bitmap width, in pixels 
2 1) ! bits/pixel 


GET_BITMAP_ID = BITMAP_ID 
END ! function 


QP RAMEE KKKEKKKEKEKKEKEKKEKKKA KKK KEK 


! * DRAW FIXED TEXT SUBROUTINE * 


QRH KICKER EK KEKE KKKKRKRKEK 


SUBROUTINE SUB_FIXED_TEXT (DOP, DOP_VAR) 


IMPLICIT INTEGER*4(A-Z) 

INCLUDE 'VWSSYSDEF’ 

! Declare the GET_BITMAP_ID function 
INTEGER*4 GET _BITMAP_ID 


! Associate the predefined structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 


INTEGER*2 OFFSET_X1 
INTEGER*2 OFFSET _Y1 


INTEGER*2 OFFSET _X2 
INTEGER*2 OFFSET_Y2 


END STRUCTURE ! Variable block 


{ Associate the Variable block w/ address 
RECORD /VARIABLE_BLOCK/ DOP_VAR 


! Load the values 

DOP. DOP$W_ITEM_TYPE = DOPSC_DRAW_FIXED_TEXT 

DOP. DOPSW_OP_COUNT = 2 

DOP.DOP$L_BITMAP_ID = GET_BITMAP_ID() { function call 


DOP.DOP$W_TEXT_HEIGHT = 8 
DOP.DOP$W_TEXT WIDTH = 8 
DOP.DOP$W_TEXT_STARTING_X = 100 
DOP.DOP$W_TEXT_STARTING_Y = 100 


DOP_VAR.OFFSET_X1 
DOP_VAR.OFFSET_Y1 


8 { reversed in memory 


Hi 


DOP_VAR.OFFSET_X2 


0 
0 
DOP_VAR.OFFSET_Y2 0 


RETURN 
END 


KHEKKKEKKKKKKKKKKRKRKKKKRKK EK 


! 
! * MOVE AREA SUBROUTINE * 
! 


KRHKKKKKEKKKEKKKKKRKRKKEKKR KKK 
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SUBROUTINE SUB_MOVE_AREA (DOP,DOP_VAR) 
INCLUDE ‘’VWSSYSDEF’ 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Associate predefined Variable Block w/ DOP.VAR 
RECORD /DOP_MOVE_ARRAY/ DOP_VAR 


! Load the MOVE AREA values 
DOP. DOPSW_ITEM_TYPE = DOPSC_MOVE_AREA 
DOP.DOP$W_OP_COUNT = 1 


DOP_VAR.DOP_MOVESW_X_SOURCE = 100 
DOP_VAR.DOP_MOVESW_Y_SOURCE = 93 !ttext is written in 
DOP_VAR.DOP_MOVESW_WIDTH = 16 tnegative direction 
DOP_VAR.DOP_MOVESW_HEIGHT = 8 

DOP_VAR.DOP_MOVESW_X_TARGET = 50 
DOP_VAR.DOP_MOVESW_Y_TARGET = 50 

RETURN 

END 
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Move/Rotate Area 


This operation describes the additional DOP structure needed to move and 
rotate an area on the screen to a specified angle (vector) and scale. 





unique block The Unique block is not relevant to this operation. 





variable block 
(dop_move_r_array) 


Field Use 
DOP_MOVE_R$W_FILLER Reserved for use by Digital 
DOP_MOVE_R$W_X_SOURCE X coordinate of the lower left corner of 


the source area (area to be moved); if a 
bitmap_ID is specified in the Common 
block, this coordinate is relative to the 
bitmap — otherwise it is viewport relative 


DOP_MOVE_R$W_Y_SOURCE Y coordinate of the lower left corner of the 
source area; if a bitmap_ID is specified 
in the Common block, this coordinate is 
relative to the bitmap — otherwise it is 
viewport relative 


DOP_MOVE_R$W_WIDTH Height of the area to be moved, in pixels 
DOP_MOVE_R$W_HEIGHT Width of the area to be moved, in pixels 
DOP_MOVE_R$W_X_TARGET X coordinate of the lower left corner of the 


target area (the area to which the source 
area is moved) 


DOP_MOVE_R$W_Y_TARGET Y coordinate of the lower left corner of the 
target area 

DOP_MOVE_R$W_X_TARGET_ X coordinate of the end point of vector 1; 

VEC1 the previously specified corner coordinates 


are used as the starting point; used to 
determine the degree of rotation 


DOP_MOVE_R$W_Y_TARGET_ Y coordinate of the end point of vector 1 
VEC1 

DOP_MOVE_R$W_L_TARGET_ Length of vector 1; determines the degree 
VEC1 of scaling 

DOP_MOVE_R$W_X_TARGET_ X coordinate of the end point of vector 2; 
VEC2 the previously specified corner coordinates 


are used as the starting point; the vector is 
used to determine the degree of rotation 


DOP_MOVE_R$W_Y_TARGET_ Y coordinate of the end point of vector 1 
VEC2 
DOP_MOVE_R$W_L_TARGET_ Length of vector 2; determines the degree 
VEC2 of scaling 


DESCRIPTION 


DOP Structures 
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The Move Rotate Area operation enables you to move (copy) a rectangular 
area from one point to another (either on the screen or in offscreen 
memory) and enables you to rotate and scale the moved copy. 


This operation also enables you to move/rotate a rectangular area of a 
bitmap identified by the bitmap ID field. 


NOTE: If the source is viewport-relative, the viewport must be unobscured and 
defined as one region for this operation to work properly. This restriction 
does not apply when the bitmap ID is specified. 


NOTE: You must specify a value for all the vector fields even if you desire no 
scaling; otherwise, your results return undefined. 


Relevant Common Block Fields 


If you specify the bitmap ID in the bitmap ID field of the Common block, 
the x_source and y_source fields of the Variable length block are considered 
offsets into the bitmap and the area you movel/rotate is from the bitmap. 
Typically, you use this feature to move, rotate, and/or scale text. 


The default writing mode loaded into the Common block (from the ATB) 
during allocation is overlay mode. When you move areas, use COPY mode. 
To load the UIS$_MODE_COPY value into the writing mode field of the 
Common block, either use the UIS$SET_WRITING_MODE routine to 
modify the ATB before allocating or use the predefined offsets to load 
the field with the value directly. WRIT$C_S (source only) is the non-UIS 
environment writing mode that corresponds to COPY. 


Initializing the Variable Block 


To move an area, you must specify the coordinates that define the lower 
left corner of the rectangle you want to move (source area), the height and 
width of the area, and the coordinates that define the lower left corner of 
the area where you are moving it (target area). 


To rotate and scale a moved area, specify two vectors, each with the 
following values: 


e Xand Y value—Specify angle of rotation 

e¢ Length value—Specifies degree of scaling 

One vector relates to the X axis, the other to the Y axis. To determine the 
proper X and Y values for the vectors, use the following formulas: 


For the X axis vector (VECTOR_1): 


x 
Y 


For Y axis vector (VECTOR_2): 


(original width, in pixels) * COS (desired angle of rotation) 
(original width, in pixels) * SIN (desired angle of rotation) 


i a 


x = -(original height, in pixels) * SIN (desired angle of rotation) 
y = (original height, in pixels) * COS (desired angle of rotation) 


Scaling factor is relative to pixels. If the original width of an area is 100 
pixels and you specify a VECTOR_1 length of 80, the area is down-scaled 
by 20%. 
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The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both X and Y source coordinates. 


a ee Ee a a a CE a A a Da OS Se SEE ETE 
EXAMPLE The following FORTRAN program draws an 11- by 16-pixel rectangle at the 


point (50,50). It then moves (copies) the rectangle to the point (150,150) 
and rotates it 90 degrees. No scaling is specified. 


PROGRAM MOVE_TEXT 

IMPLICIT INTEGER*4(A-Z) 
INCLUDE 'UISENTRY’ 

INCLUDE 'UISUSRDEF’ 

INCLUDE 'VWSSYSDEF’ 

INTEGER*4 WD_ID, VD_ID 
COMMON /WINDOW/ WD_ID, VD_ID 


! Create a display and window 


VD_ID = UISSCREATE_DISPLAY (0.0,0.0, lower left corner 


! 
2 50.0,50.0, ! upper right corner 
2: 15.0,15.0) ! width & height 
WD_ID = UISSCREATE_WINDOW (VD_ID, ! display ID 
2 ‘SYSSWORKSTATION’, ! device name 
! 


2 ‘DOP Drawing Window’ ) window banner 


! Allocate the DOP for DRAW_LINES 

SIZE = (4 * DOP_LINESC_LENGTH) 

DOP = UISDCSALLOCATE_ DOP (WD_ID, ! window ID 

2 SIZE, ! variable portion size, in bytes 
2 0) ! default ATB number 


{ Call the DRAW LINES subroutine 
CALL D_LINES (%VAL(DOP), ! DOP address, by value 
2 %VAL(DOP+DOPSC_LENGTH) ) ! Var. block address 


! Queue the DOP asynchronously 
CALL UISDCSQUEUE_DOP (WD_ID, 
2 %VAL(DOP) ) 


window ID 
DOP address, by value 


! Modify the writing mode in ATB 
CALL UISSSET_WRITING_MODE (VD_ID, 


2 0, ! default ATB 
2 1, { modified ATB 
2 UISS$C_MODE_COPY) ! new mode 


! Allocate the DOP for MOVE_ROTATE 

SIZE = DOP_MOVE_RSC_LENGTH 

DOP1 = UISDCSALLOCATE_DOP (WD_ID, ! window ID 

2 SIZE, ! size, in bytes 

2 1) ! number of modified ATB 


! Call the MOVE_ROTATE subroutine 
CALL SUB_MOVE_ROTATE (%VAL(DOP1), 
2 %VAL(DOP1+DOP$C_LENGTH) ) 


! Queue the DOP asynchronously 
CALL UISDCSQUEUE_DOP (WD_ID, ! window ID 
2 %VAL(DOP1) ) ! DOP address, by value 


CALL SYSSHIBER( ) 


END 


KKKKKKEKKKEKKKKKKK KKK KKK K 


!* 
! * DRAW LINES SUBROUTINE * 
RIOR IOI OR IOI KIO 


SUBROUTINE D_LINES (DOP, DOP_VAR) 


5-57 


DOP Structures 
Move/Rotate Area 


INCLUDE 


! Associate the predefined structure w/ DOP 


‘VWSSYSDEF’ 


RECORD /DOP_STRUCTURE/ DOP 


! Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 


INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 


INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 


INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 


END STRUCTURE 


FIRST_LINE_X1 
FIRST_LINE_Y1 
FIRST_LINE_X2 
FIRST_LINE_Y2 


SECOND_LINE_X1 
SECOND_LINE_Y1 
SECOND_LINE_X2 
SECOND_LINE_Y2 


THIRD_LINE_X1 
THIRD_LINE_Y1 
THIRD_LINE_X2 
THIRD_LINE_Y2 
FOURTH_LINE_X1 
FOURTH_LINE_Y1 
POURTH_LINE_X2 
FOURTH_LINE_Y2 


! dop_structure 


! Associate the structure with the DOP_VAR address 
RECORD /VARIABLE_BLOCK/ DOP_VAR 


! Load the DRAW_LINE values 
DOP.DOP$W_ITEM_TYPE = DOPSC_DRAW_LINES 


DOP.DOP$W_OP_COUNT = 4 


DOP_VAR.FIRST_LINE_X1 = 50 

DOP_VAR.FIRST_LINE_Y1 = 50 

DOP_VAR.FIRST LINE_X2 = 50 

DOP_VAR.FIRST_LINE_Y2 = 65 

DOP_VAR.SECOND_LINE_X1 = 50 
DOP_VAR.SECOND_LINE_Y1 = 65 
DOP_VAR.SECOND_LINE_X2 = 60 
DOP_VAR.SECOND_LINE_Y2 = 65 
DOP_VAR.THIRD_LINE_X1 = 60 

DOP_VAR.THIRD_LINE_Y1 = 65 

DOP_VAR. THIRD LINE_X2 = 60 

DOP_VAR.THIRD_LINE_Y2 = 50 

DOP_VAR.FOURTH_LINE_X1 = 60 
DOP_VAR.FOURTH_LINE_Y1 = 50 
DOP_VAR.FOURTH_LINE_X2 = 50 
DOP_VAR.FOURTH_LINE_Y2 = 50 
RETURN 

END 


PRI II KK KKK KK KKK KEK KEKE KEKE 


{ * MOVE ROTATE SUBROUTINE * 


Po RAKHI KIRK EKEKKEK KK EKKKKKK KKK 


SUBROUTINE SUB_MOVE_ROTATE (DOP, DOP_VAR) 
INCLUDE ‘VWSSYSDEF’ 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Associate the predefined variable structure w/ DOP_VAR 
RECORD /DOP_MOVE_R_ARRAY/ DOP_VAR 


! Load the values 
DOP.DOPSW_ITEM_TYPE = 
DOP.DOP$W_OP_COUNT = 1 


DOPS$C_MOVE_ROTATE_AREA 
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DOP_VAR.DOP_MOVE_RSW_X_SOURCE = 50 
DOP_VAR.DOP_MOVE_RSW_Y_SOURCE = 50 
DOP_VAR.DOP_MOVE_RSW_WIDTH = 11 
DOP_VAR.DOP_MOVE_RSW_HEIGHT = 16 
DOP_VAR.DOP_MOVE_RSW_X_TARGET = 150 
DOP_VAR.DOP_MOVE_RS$W_Y_TARGET = 150 
DOP_VAR.DOP_MOVE_RSW_X_TARGET_VEC1 
DOP_VAR.DOP_MOVE_RS$W_Y_TARGET_ VEC1 
DOP_VAR.DOP_MOVE_RSW_L_TARGET_VEC1 
DOP_VAR.DOP_MOVE_RSW_X_TARGET VEC2 = (-16 * SIND(90.)) 
DOP_VAR.DOP_MOVE_RSW_Y_TARGET_VEC2 = (16 * COSD(90.)) 
DOP_VAR.DOP_MOVE_RSW_L_TARGET_VEC2 = 16 


(11 * COSD(90.)) 
(11 * SIND(90.)) 
11 


RETURN 
END 
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Resume Viewport Activity 


This operation describes the additional DOP structure needed for a system 
viewport to resume activity on a suspended viewport. 





unique block 
(stop_args) 


Field Use 


DOP$L_DRIVER_VP_ID | The viewport ID associated with the request queue 
to be resumed 





DESCRIPTION The Resume Viewport Activity operation resumes activity on a viewport 
that was suspended with the Suspend Viewport Activity DOP (or Suspend 
Viewport Activity QIO function). 


Because the target viewport is suspended, this DOP must be inserted 
on the queue of a viewport that is not suspended. In most cases, the 
systemwide viewport is used to resume suspended viewports. 


Initializing the Unique Block 


The Unique block specifies the viewport ID of the viewport to be resumed. 
You obtain the viewport ID with the Get Viewport ID QIO at viewport 
creation time. 


initializing the Variable Block 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both X and Y source coordinates. 





EXAMPLE The following FORTRAN program resumes activity on a viewport whose ID 
is passed to the subroutine: 


Calling Program 


. 
LKR KHKEKEKKEKEKEKEKEKEKEKEKK KKK 


* RESUME SUBROUTINE * 


LAKH KKKEKKKKKKKKKKK KEK 


- 


SUBROUTINE RESUME (DOP, DOP_VAR, VP_ID) 
INCLUDE ’VWSSYSDEF’ 


{ Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Load the value 
DOP..DOP$SW_ITEM_TYPE = DOPSC_RESUME 
DOP.DOPSW_OP_COUNT = 1 
DOP.DOP$L_DRIVER_VP_ID = VP_ID 
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RETURN 
END 


5-61 


DOP Structures 
Scroll Area 


Scroll Area 


unique block 


variable block 
(dop_move_array) 


This operation describes the additional DOP structure needed to scroll the 
screen display. 





The Unique block is not relevant to this operation. 





Field Use 

DOP_MOVE$W_FILLER Reserved for use by Digital _ 

DOP_MOVE$W_X_SOURCE X coordinate of the lower left corner of the 

. source area (area to be moved) 

DOP_MOVE$W_Y_SOURCE Y coordinate of the lower left corner of the 
source area 

DOP_MOVE$W_WIDTH Height of the area to be moved, in pixels 

DOP_MOVE$W_HEIGHT Width of the area to be moved, in pixels 

DOP_MOVE$W_X_TARGET X coordinate of the lower left corner of the target 
area (the area to which the source area is moved) 

DOP_MOVE$W_Y_TARGET Y coordinate of the lower left corner of the target 
area 


Variable-Length Constant: dop_move$c_length 





DESCRIPTION 


5-62 


The Scroll Area operation permits you to move (copy) a rectangular area 
either on the screen or in offscreen memory. It differs from the Move Area 
operation in that it erases (fills with background color) the area specified as 
the source. This operation is typically used for onscreen scrolling. 


Relevant Common Block Fields 


Scroll Area always uses the copy writing mode. It ignores any value 
currently contained in the writing_mode field. 


Initializing the Variable Block 


To scroll an area, specify the coordinates that define the lower left corner 
of the rectangle you want to move (source area), the height and width of 
the area, and the coordinates that define the lower left corner of the area 
where you are moving it (target area). 


DOP Structures 
Scroll Area 





EXAMPLE The following FORTRAN program scrolls an 11- by 16-pixel rectangle from 
the point (50,50) to the point (50,150). 


PROGRAM SCROLL 
IMPLICIT INTEGER*4(A-Z) 
INCLUDE 'UISENTRY’ 

INCLUDE 'UISUSRDEF’ 

INCLUDE ’VWSSYSDEF’ 

COMMON /WINDOW/ WD_ID, VD_ID 


! Create a display and window 


VD_ID = UISSCREATE_DISPLAY (0.0,0.0, lower left corner 


i 
2 50.0,50.0, ! upper right corner 
2 15.0,15.0) ! width & height 
WD_ID = UIS$CREATE_WINDOW (VD_ID, ! display ID 
2 'SYSSWORKSTATION’, ! device name 
2 ‘DOP Drawing Window’) ! window banner 


! Allocate the DOP for DRAW_LINES 


SIZE = (4 * DOP_LINE$C_LENGTH) 

DOP = UISDCSALLOCATE_DOP (WD_ID, ! window ID 

2 SIZE, ! variable portion size, in bytes 
2 0) ! default ATB number 

! Call the DRAW LINES subroutine 

CALL D_LINES (%VAL(DOP), ! DOP address, by value 

2 %VAL(DOP+DOP$C_LENGTH) ) ! Var. block address 

! Queue the DOP asynchronously 

CALL UISDCSQUEUE_DOP (WD_ID, ! window ID 

2 %VAL(DOP) } ! DOP address, by value 


! Modify the writing mode in ATB 
CALL UISSSET_WRITING_MODE (VD_ID, 


2 0, ! default ATB 
2 L, ! modified ATB 
2 UIS$C_MODE_COPY) ! new mode 


! Allocate the DOP for SCROLL 
SIZE = DOP_MOVESC_LENGTH 

DOP1 = UISDCSALLOCATE_DOP (WD_ID, 
2 SIZE, 
2 1) 


window ID. 
size, in bytes 
number of modified ATB 


—- o- om 


! Call the MOVE_ROTATE subroutine 
CALL SUB_SCROLL (%*VAL(DOP1), 


2 %VAL(DOP1+DOP$C_LENGTH) ) 

t Queue the DOP asynchronously 

CALL UISDCS$QUEUE_DOP (WD_ID, ! window ID 

2 %VAL(DOP1) ) ! DOP address, by value 


CALL SYS$HIBER() 
END 


QRH KKK KKK KKKEK KKK KEK K 


! * DRAW LINES SUBROUTINE * 


PRI RR RIOR ROR ROTOR RK IIR BK 
SUBROUTINE D_LINES (DOP, DOP_VAR) 
INCLUDE ‘VWSSYSDEF’ 


! Associate the predefined structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Build the Variable Block 
STRUCTURE /VARIABLE_BLOCK/ 
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INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 


INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 


INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 


INTEGER* 2 
INTEGER* 2 
INTEGER* 2 
INTEGER* 2 


END STRUCTURE 


FIRST_LINE_X1 
FIRST LINE_Y1 
FIRST _LINE_X2 
FIRST _LINE_Y2 


SECOND_LINE_X1 
SECOND_LINE_Y1 
SECOND_LINE_X2 
SECOND_LINE_Y2 


THIRD_LINE_X1 
THIRD_LINE_Y1 
THIRD_LINE_X2 
THIRD_LINE_Y2 


FOURTH_LINE_X1 
FOURTH_LINE_Y1 
FOURTH_LINE_X2 
FOURTH_LINE_Y2 


! dop_structure 


t Associate the structure with the DOP_VAR address 
RECORD /VARIABLE_BLOCK/ DOP_VAR 


! Load the DRAW_LINE values 


DOP.DOPSW_ITEM_TYPE = 


DOP.DOPSW_OP_COUNT = 4 


DOP_VAR. FIRST_ 
DOP_VAR.FIRST_ 
DOP_VAR.FIRST_ 
DOP_VAR.FIRST_ 


DOP_VAR.SECOND_LINE_X1 = 
DOP_VAR.SECOND_LINE_Y1 
DOP_VAR.SECOND_LINE_X2 
DOP_VAR.SECOND LINE_Y2 = 


DOP_VAR.THIRD_LINE_X1 = 
DOP_VAR.THIRD_LINE_Y1 
DOP_VAR.THIRD_LINE_X2 
DOP_VAR.THIRD_LINE_Y2 = 


DOP_VAR.FOURTH_LINE_X1 = 
DOP_VAR.FOURTH_LINE_Y1 
DOP_VAR.FOURTH_LINE_X2 
DOP_VAR.FOURTH_LINE_Y2 = 


RETURN 
END 


I 
ui 
oO 


LINE_X1 = 
LINE_Y1 
LINE_X2 
LINE_Y2 = 
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DOPS$C_DRAW_LINES 


] HRI KK KEKE IK 


{ * SCROLL 


SUBROUTINE * 


QRH HIRI RIKKKEKKIKEKKEEKEKEKEKKKEK 


SUBROUTINE SUB_SCROLL (DOP, DOP_VAR) 


INCLUDE 


'VWSSYSDEF’ 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Associate the predefined variable structure w/ DOP_VAR 
RECORD /DOP_MOVE_ARRAY/ DOP_VAR 


! Load the values 


DOP.DOPSW_ITEM_TYPE = 


DOP.DOP$W_OP_COUNT = 1 


DOP_VAR.DOP_MOVE$W_X_SOURCE 
DOP_VAR.DOP_MOVESW_Y_SOURCE 
DOP_VAR.DOP_MOVESW_WIDTH = 1 
DOP_VAR.DOP_MOVES$W_HEIGHT = 
DOP_VAR.DOP_MOVESW_X_TARGET 
DOP_VAR.DOP_MOVESW_Y_TARGET 


1 


16 


DOP$C_SCROLL_AREA 


50 
50 


50 
150 
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RETURN 
END 
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Start Request Queue 


unique block 
(stop_args) 


This operation describes the additional DOP structure needed for the 
system viewport to restart a stopped request queue on another viewport. 





Field Use 
DOP$L_DRIVER_VP_ID Viewport ID associated with the request queue to 
be started 


DESCRIPTION 


The Start Request Queue operation starts (or restarts) the processing of 
packets on the request queue of the specified viewport. 


Typically, this call is made after the queue has been stopped with the 
Stop operation. Since the target viewport is stopped, this DOP must be 
inserted on the queue of a viewport that is not stopped. In most cases, the 
systemwide viewport is used to start stopped viewports. 


Initializing the Unique Block 


The Unique block specifies the viewport ID of the viewport to be started. 
Obtain the viewport ID with the Get Viewport ID QIO at viewport creation 
time. 


Initializing the Variable Block 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both X and Y source coordinates. 


EXAMPLE 


The following FORTRAN program starts activity on a viewport whose ID is 
passed to the subroutine: 


! Calling Program 


PIII IIR RR RIOR KI 
! * START SUBROUTINE * 


YP RAKHI KEKEKEKEKK 


SUBROUTINE START (DOP, DOP_VAR, VP_ID) 
INCLUDE ‘VWSSYSDEF’ 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


{ Load the value 
DOP.DOPSW_ITEM_TYPE = DOPSC_START 
DOP.DOPSW_OP_COUNT = 1 
DOP.DOP$L_DRIVER_VP_ID = VP_ID 
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RETURN 
END 
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Stop Request Queue 


This operation describes the additional DOP structure needed to stop 
removing entries from the specified viewport request queue. 





unique block 


(stop_args) 
Field Use 
DOP$L_DRIVER_VP_ID Viewport ID associated with the request queue to 
be stopped 


SE aaa aaa ae Ne Tene Oe I I PET eT OO SBN ET NE DY ae IO 

DESCRIPTION | The Stop Request Queue operation stops processing on the request queue 
of the specified viewport to give the calling process control over the 

| viewport bitmap. Stopping a viewport request queue ensures that no other 

process will modify the bitmap of the stopped viewport. To guarantee 
that all previously queued DOPs are processed, insert this DOP on the 
queue with the Insert DOP QIO or the Execute DOP UISDC routine. Stop 
differs from Suspend in that Stop waits for any DOPs already processing to 
complete before returning control. 


A viewport management task typically uses this operation to change the 
position or occlusion of any viewport in the system (with the Set Viewport 
Region QIO). 


Once the Stop operation is invoked, no further commands can be executed 
from the request queue unless the request queue is explicitly restarted 
with the Start Request Queue QIO or DOP (from a viewport other than the 
stopped one). 


Initializing the Unique Block 


The Unique block specifies the viewport ID of the viewport to be stopped. 
Obtain the viewport ID with the Get Viewport ID QIO at viewport creation 
time. ; 


Initializing the Variable Block 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both X and Y source coordinates. 
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EXAMPLE The following FORTRAN program stops activity on a viewport whose ID is 
passed to the subroutine. 


! Calling Program 


YE KEKE KEKE KK KEKKKEKK KEK KK 


! * STOP SUBROUTINE * 


PRK KKKKKEKKEKKKEKKKEKKK 


SUBROUTINE STOP (DOP, DOP_VAR, VP_ID) 
INCLUDE ‘VWSSYSDEF’ 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


{ Load the value 
DOP.DOPSW_ITEM_TYPE = DOPSC_STOP 
DOP.DOP$W_OP_COUNT = 1 
DOP.DOPSL_DRIVER_VP_ID = VP_ID 


RETURN 
END 
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Suspend Viewport Activity 


This operation describes the additional DOP structure to suspend activity 
on a viewport. 





unique block 


(stop_args) 
DOP$L_DRIVER_VP_ID 0 
Field Use 
DOP$L_DRIVER_VP_ID The viewport ID associated with the request queue 


to be suspended 





DESCRIPTION The Suspend Viewport Activity operation suspends activity on a specified 
viewport. 


Typically, this operation is used to synchronize drawing operations. When 
operations are completed, you can resume activity on the viewport by 
issuing a $QIO request to resume viewport activity (see Chapter 4) or 
invoking the Resume DOP (from a viewport other than the stopped one). 
Think of Suspend and Resume as the drawing parallels to the CTRL/S and 
CTRL/Q key functions. 


Stop differs from Suspend in that Stop waits for any DOPs already 
processing to complete before returning control. 


Initializing the Unique Block 


The Unique block specifies the viewport ID of the viewport to be 
suspended. Obtain the viewport ID with the Get Viewport ID QIO at 
viewport creation time. 


Initializing the Variable Block 


The QDSS bitmap-memory coordinate system uses an X coordinate that 
increases from left to right and a Y coordinate that increases down. For 
example, to access the top left corner of a bitmap in QDSS memory, 
specify 0 for both X and Y source coordinates. 
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EXAMPLE The following FORTRAN program suspends activity on a viewport whose 
ID is passed to the subroutine. 


! Calling Program 


° 
QRH KEKKKEKKKKKKKK KEK 


! * SUSPEND SUBROUTINE * 


RHEE KKKKEKKEKKKEK KK KK 


SUBROUTINE SUSPEND (DOP, DOP_VAR, VP_ID) 
INCLUDE ‘'VWSSYSDEF’ 


! Associate the predefined fixed structure w/ DOP 
RECORD /DOP_STRUCTURE/ DOP 


! Load the value 
DOP.DOPS$W_ITEM_TYPE = DOPS$C_SUSPEND 
DOP.DOPSW_OP_COUNT = 1 
DOP.DOPS$L_DRIVER_VP_ID = VP_ID 


RETURN 
END 
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5.7 UISDC DOP Interface 


The UISDC DOP interface enables applications that draw within UIS 
viewports to use DOPs. The five UISDC routines that compose the 
interface follow. 


¢ UISDC$ALLOCATE_DOP—Allocate storage for a DOP 


e UISDC$LOAD_BITMAP—Load bitmaps from processor memory into 
offscreen bitmap memory (for subsequent use by text or fill pattern 
DOPs) : 


e UISDC$EXECUTE_DOP_ ASYNCH, UISDC$EXECUTE_DOP_SYNCH, 
and UISDC$QUEUE_DOP—Submit DOPs to the request queue for 
execution 


This section describes each routine. 


Section 5.3.1 describes how to use UISDC$ALLOCATE_DOFP to allocate 
DOPs. 


Section 5.3.2 describes how to use UISDC$EXECUTE_DOP_ASYNCH, 
UISDC$EXECUTE_DOP_SYNCH, and UISDC$QUEUE_DOFP to execute 
DOPs (and how they differ from one another). 


Section 5.7.1 describes how to use UISDC$LOAD_BITMAP. 


5.7.1. Loading Bitmaps into Offscreen Memory 
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Use the UISDC$LOAD_BITMAP routine to load a bitmap. UISDC$LOAD_ 
BITMAP returns a bitmap identifier (a handle) when you specify a window 
ID (where the bitmap will be used), the bitmap address, the length and _ 
width of the bitmap, and the number of bits per pixel (more than one on 
color systems). 


Use UISDC$LOAD_BITMAP two ways. 


1 The bitmap is copied from the user buffer into a driver-maintained 
buffer. When the bitmap is accessed, it is copied from the driver- 
maintained buffer into offscreen memory. 


2 A handle (identifier) is created for the bitmap, but the routine relies on 
the application to supply the bitmap when it is accessed. This second 
method saves space by not loading bitmaps until they are actually 
accessed. 


To have the driver maintain the bitmap, specify the address of the bitmap 
in process memory as the bitmap address parameter. To access the bitmap 
in a subsequent DOP, load the bitmap_ID field of the DOP Common block 
with the bitmap ID returned by Load Bitmap. The system handles the 
storage of this bitmap. 


When the system manages bitmap storage, it uses the bitmap glyph as a 
backing store address if it has to swap the bitmap out of offscreen memory. 
That is, when the bitmap is accessed, the system uses the bitmap glyph to 
swap the bitmap back into offscreen memory. 
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To load a bitmap dynamically, specify 0 as the bitmap address parameter, 
but still specify the correct length, width, and bits-per-pixel. To access the bitmap 
in a subsequent DOP, load the bitmap_ID field of the DOP Common block 
with the bitmap ID returned by LOAD_BITMAP and load the bitmap_glyph 
field of the Common block with the address of the bitmap in processor 
memory. 


When you specify a bitmap address of 0 and put the true address in the 
bitmap_glyph field, you save system resources. The bitmap is not loaded 
until it is accessed, and the application, not the system, is responsible for 
saving the bitmap (when it is swapped out, it is unknown by the system). 
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UISDC$ALLOCATE_DOP—Allocate Drawing Packet 


This routine allocates a driver DOP for a particular display window. 








FORMAT dop_address = UISDC$ALLOCATE_DOP_  wd_id,size 
,atb 
RETURNS VMS Usage: address 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword value returned as the address of the DOP in the variable dop_ 
address or RO (VAX MACRO). Used in subsequent execution calls. 


UISDC$ALLOCATE_DOP signals all errors; no condition values are 
returned. 





ARGUMENTS~ wd_id 
VMS Usage: identifier 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


The window identifier. The wd_id argument is the address of a longword 
that uniquely identifies the display window. This routine associates the 
DOP with a window by loading the viewport-related fields of the Common 
block with the coordinates from the specified window (to determine the 
clipping rectangle). The window identifier is returned to an application 

at viewport creation time. See UISSCREATE_WINDOW in the VMS 
Workstation Software Graphics Programming Guide for more information 
about the wd_id argument. 


size 

VMS Usage: longword_unsigned 
type: longword (unsigned) 
access: modify 


mechanism: by reference 


Size of the variable portion of the DOP, in bytes. On input, the size 
argument is the address of a number that defines the requested size of the 
variable portion of the DOP to be allocated. 


On output, it is the size of the variable portion of the DOP that was actually 
allocated. The size allocated might be smaller than the size you request. 
Always use the returned size in subsequent operations. 


atb 

VMS Usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
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mechanism: by reference 


Attribute block number. The atb argument is the address of the attribute 
block which is used to initialize the color, writing_mode, and. writing_mask 
fields of the Common block. 
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UISDC$LOAD_BITMAP 


UISDC$LOAD_BITMAP—Load Bitmap 


This routine loads a bitmap from processor memory into offscreen memory. 


FORMAT bitmap_id=UISDC$LOAD_BITMAP wc_id 
,bitmap_adr 
,bitmap_len 








,bitmap_width 
, bits_per_pixel 
RETURNS VMS Usage: identifier 
type: longword (unsigned) 
access: write only 


mechanism: by value 


Longword value returned as the bitmap identifier in the variable bitmap_id 
or RO (VAX MACRO). This value is used in DOP$L_BITMAP_ID field of 
subsequent driver DOPs. 


UISDC$LOAD_BITMAP signals all errors; no condition values are 
returned. 
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ARGUMENTS~ wd_id 

VMS Usage: identifier 

type: longword (unsigned) 

access: read only 

mechanism: by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies a display window. The window identifier 
is returned to an application at viewport creation time. See UIS$CREATE_ 
WINDOW in the VMS Workstation Software Graphics Programming Guide for 
more information about the wd_id. 


bitmap_adr 

VMS Usage: address 

type: longword (unsigned) 
access: read only 
mechanism: by reference 


Bitmap address. The bitmap_adr argument is the address of a bitmap 
located in processor memory. 


bitmap_len 

VMS Usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 
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Bitmap length. The bitmap_len argument is the address of the number that 
defines the length of the bitmap in bytes. The length must be a multiple of 
2. 


bitmap_width 


VMS Usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Width of the bitmap. The bitmap_width argument is the address of a 
number that defines the width of the bitmap in pixels. If the width of the 
bitmap is greater than 1024, the bitmap wraps. Single-plane bitmaps must 
have a width that is a multiple of 16. 


bits_per_pixel 

VMS Usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


The bits_per_pixel argument is the address of a number that defines the 
number of bits per pixel. Currently, the values 1 and 8 are supported. 





DESCRIPTION 


UISDC$LOAD_BITMAP loads a bitmap that resides in processor memory 
into the bitmap portion of offscreen memory. It returns a bitmap ID for 
the loaded bitmap that can be used in DOPs that require a bitmap ID (fill 
operations and text operations). In those cases, the returned bitmap ID is 
loaded into the DOP$C_BITMAP _ID field of the Common block. 
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UISDCS$EXECUTE_DOP_ASYNCH—Execute Drawing 
Operation | 
Primitive 
Asynchronously 


This routine starts execution of the specified DOP in the specified display 
window and immediately returns control to the application. 





FORMAT UISDCSEXECUTE_DOP_ASYNCH wo_id 





,dop_address 
,losb 
RETURNS UISDC$EXECUTE_DOP_ASYNCH signals all errors; no condition values 


are returned. 





ARGUMENTS~ wd_id 
VMS Usage: identifier 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. The window 
identifier is returned to an application at viewport creation time.’ See 
UIS$CREATE_WINDOW in the VMS Workstation Software Graphics 
Programming Guide for more information about the wd_id argument. 


dop_address 

VMS Usage: vector_byte_unsigned 
type: byte_unsigned 
access: read only 

mechanism: by reference 


Drawing Operation Primitive. The dop_address argument is the address of 
an array of bytes that compose the DOP. This address is returned by the 
UISDC$ALLOCATE_DOP routine. 


losb 

VMS Usage: cond_value 

type: longword (unsigned) 
access: write only 


mechanism: by reference 


I/O status block. The iosb argument is the address of an I/O status block 
that receives a value indicating that the DOP is queued for execution. The 
IOSB also receives notification when the DOP is completed. 


UISDC Routines 
UISDC$EXECUTE_DOP_ASYNCH 





DESCRIPTION  UISDCSEXECUTE_DOP_ASYNCH queues the specified DOP for 
execution in the specified window request queue. The execution is 
performed asynchronously; the DOP is queued for execution, but control is 
immediately returned to the application. Use the IOSB to determine when 
the DOP has actually completed. 
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UVISDCSEXECUTE_DOP_SYNCH—Execute Drawing 
Operation 
Primitive 
Synchronously 


This routine executes the specified DOP in the specified display window 
and returns control to the application. 








FORMAT UISDCSEXECUTE_DOP_SYNCH wa_id 
,dop_address 
RETURNS UISDC$EXECUTE_DOP_SYNCH signals all errors; no condition values are 
returned. 





ARGUMENTS~ wd_id 
VMS Usage: identifier 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. The window 
identifier is returned to an application at viewport creation time. See 
UIS$CREATE_WINDOW in the VMS Workstation Software Graphics 
Programming Guide for more information about the wd_id argument. 


dop_address 

VMS Usage: vector_byte_unsigned 
type: byte_unsigned 
access: read only 

mechanism: by reference 


Drawing Operation Primitive. The dop_address argument is the address of 
an array of bytes that compose the DOP. This address is returned by the 
UISDC$ALLOCATE_DOP routine. 





DESCRIPTION  UISDCSEXECUTE_DOP_SYNCH queues the specified DOP for execution 
on the specified window request queue. The execution is performed 
synchronously; the DOP is queued for execution, and EXECUTE_DOP_ 
SYNCH waits until the operation is complete before returning control to 
the application. 


UISDC Routines 
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UVISDCSQUEUE_DOP—Queue Drawing Operation 
Primitive 


This routine queues the specified DOP for execution in the specified 
window and returns control to the application. 





FORMAT UISDC$QUEUE_DOP_ wd_id ,dop_address 





RETURNS UISDC$QUEUE_DOP signals all errors; no condition values are returned. 





ARGUMENTS~ wd_id 
VMS Usage: identifier 
type: longword (unsigned) 
access: read only 
mechanism: by reference 


Display window identifier. The wd_id argument is the address of a 
longword that uniquely identifies the display window. The window 
identifier is returned to an application at viewport creation time. See 
UIS$CREATE_WINDOW for more in the VMS Workstation Software Graphics 
Programming Guide information about the wd_id argument. 


dop_address 

VMS Usage: vector_byte_unsigned 
type: byte_unsigned 
access: read only 

mechanism: by reference 


Drawing Operation Primitive. The dop_address argument is the address of 
an array of bytes that compose the DOP. This address is returned by the 
UISDC$ALLOCATE_DOP routine. 
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DESCRIPTION  UISDCSQUEUE_DOP queues the specified DOP for execution in 
the specified window request queue. The execution is performed _ 
asynchronously; the DOP is queued for execution, but control 
is immediately returned to the application. This differs from 
UISDC$EXECUTE_DOP_ASYNCH in that with UISDC$QUEUE_DOP, 
you cannot determine when the DOP has actually completed. 
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This appendix illustrates and describes the data structures common to the 
QOVSS and QDSS systems. 





button simulation 
block 


buttons to be pressed mask 
buttons to be released mask 















Field Use 
Buttons to be pressed mask Mask of the buttons to be pressed. 
Buttons to be released mask Mask of the buttons to be released. 


Pointer button definitions used in the masks 
are defined by the $QVBDEF macro. They 
consist of the following symbols: 


Symbol Meaning 
QV$M_BUTTON_1 Select button 
QV$M_BUTTON_2 Button 2 
QV$M_BUTTON_3 ~~ Button3 
QV$M_BUTTON_4 Button 4 


Oo 


This longword must be zero. 


(a) 


This longword must be zero. 





cursor hot spot 


Y offset 
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The Pointer Cursor Hot Spot data type defines the pointer cursor hot spot, 
which is that point within the 16- x 16-pixel cursor display region that is the 
actual cursor position. 


Field Use 

X offset X offset from the upper left corner of the 
pointer pattern to the active point. 

Y offset Y offset from the upper left corner of the 


pointer pattern to the active point. 
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data rectangle 
values block 














MINX (left side value) 0 
MINY (bottom side value) 4 
MAXX (right side value) 8 
MAXY (top side value) 12 
Field Use 
MINX (left side value) Pixel value for left side of rectangle. 
MINY (bottom side value). Pixel value for bottom side of rectangle. 
MAXX (right side value) Pixel value for right side of rectangle. 
MAXY (top side value) Pixel value for top side of rectangle. 
keyboard request 
ast specification 
block 
AST service routine address 0 
AST parameter 4 
: 
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Field 


AST service routine address 


AST parameter 


Access mode 
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Use 


The AST service routine address is 0 if no 
AST action routine is required. If no AST 
routine is specified, input is stored in the 
type-ahead buffer and delivered either when 
an AST region is declared or when a Get 
Next Input Token QIO is issued. 


The user-defined AST parameter is delivered 
to the AST action routine. It is not examined 
by the driver. 


The access mode to deliver the AST is 
maximized with the current access mode. 


The fourth longword must be zero. 





keyboard 
characteristics 
block 
| enabled characteristics mask 0 
disabled characteristics mask 4 
keyclick volume 8 
<a, a Nee ” 
Field Use 
Enabled The first longword is a mask of characteristics to be 
characteristics mask enabled. 
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Field 


Disabled 
characteristics mask 


Use 


The second longword is a mask of characteristics to be 


disabled. 


The keyboard characteristics, defined by the $QVBDEF 
macro, consist of the following bits: 


Characteristic Default Meaning 
QV$M_KEY_ On Key held down 
AUTORPT automatically repeats. 
QV$M_KEY_ On Keyclick sounds on each 
KEYCLICK keystroke. 
QV$M_KEY_UDF6 Off Function keys F6 through 
F10 generate up/down 
transitions. 
QV$M_KEY_UDF11 Off Function keys F11 through 
F14 generate up/down 
transitions. 
QV$M_KEY_UDF17 Off Function keys F17 through 
F20 generate up/down 
transitions. 
QV$M_KEY_ Off Function keys HELP and 
UDHELPDO DO generate up/down 
transitions. 
QV$M_KEY_UDE1 Off Function keys E1 through 
E6 generate up/down 
transitions. 
QV$M_KEY_ Off Arrow keys generate 
UDARROW up/down transitions. 
QV$M_KEY_ Off Numeric keypad keys 
UDNUMKEY generate up/down 


transitions. 


Keyclick volume The keyclick volume is a value from 1 (loudest) to 8 


(softest). If a value of 0 is specified, the current system 
default keyclick volume is used. 


0 The fourth longword must be 0. 
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keystroke ast 













specification 

block 

: 
: 
: 
: 


Field Use 


AST service routine address The AST service routine address is 0 if no 
AST action routine is required. If no AST 
routine is specified, input is stored in the 
type-ahead buffer and delivered either when 
an AST region is declared or when an Get 
Next Input Token QIO is issued. 


AST parameter The user-defined AST parameter is delivered 
to the AST action routine. It is not examined 
by the driver. 


Access mode The access mode to deliver the AST is 
maximized with the current access mode. 
Input token address The input token address is the address 


of a longword that receives an input token 
when an AST routine is called. Word 0 of 
the longword contains token or character 
data. Values from 0 to 255 map into the 
Digital multinational character set. Values 
from 256 to 512 map function keys into token 
values. Word 1 of the longword contains 
control information; bit 15 defines the status 
of a token (1 equals down, 0 equals up). By 
default an AST is only signaled on a down 
transition. 
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pointer button 
characteristics 
block 








Field Use 


enabled characteristics mask 
disabled characteristics mask 









Enabled Longword of characteristics to be enabled. 


characteristics mask 


Disabled Longword of characteristics to be disabled. 


characteristics mask 


The pointer button characteristics, defined by the $QVBDEF 


macro, consist of the following bits: 


Characteristic Default Meaning 


QV$M_BUT_ On 
UPTODOWN 


0 This longword must be zero. 
0 This longword must be zero. 


pointer 
characteristics 
block 
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After a pointer button 
down transition occurs, 
the current pointer button 
request receives all future 
pointer button transitions 
until all pointer buttons 
return to the up position 
(regardless of the position 
of the pointer cursor on 
the physical screen). 

If this characteristic is 
disabled, then each up 
and down transition is 
delivered to the active 
button request for the 
current pointer cursor 
position. ; 
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a 
aes icra id 
i Sa | 
ee 





Field Use 
Enabled characteristics The first longword is a mask of characteristics to be 
mask enabled. 


Disabled characteristics The second longword is a mask of characteristics to be 
mask disabled. 


The pointer characteristics, defined by the $QVBDEF 
macro, consist of the following bits: 


Characteristic Meaning 
QV$M_PTR_LEFT_ Invert buttons on mouse or 
HAND puck. (Buttons 1 and 3 are 
switched.) 
QV$M_PTR_INVERT_. Invert buttons on stylus. 
STYLUS (Buttons 1 and 3 are 
switched.) 
0 Must be 0. 
0 Must be 0. 





pointer motion 
ast specification 
block 






ee 
i 
a 

12 





address of new pointer cursor position 


Field Use 





AST service routine AST service routine address is 0 if no AST action 
address routine is required. No buffering of data in the type- 


' ahead buffer occurs for pointer motion ASTs. 
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Field Use 

AST parameter The user-defined AST parameter is delivered to the 
AST action routine. it is not examined by the driver. 

Access mode The access mode to deliver the AST is maximized with 
the current access mode. 

Address of new pointer The fourth longword contains the address of a longword 

cursor position to receive the new pointer cursor position when the AST 


routine is called. (If the information is not required, this 
longword is 0.) The low-order word contains the new 

X pixel location of the pointer cursor; the high-order 
word contains the new Y pixel location of the cursor. 
For screen pointers, X is value 0 through 1023 with the 
lowest value denoting the left side of the screen; Y is 
value 0 through 863 with the lowest value denoting the 
bottom of the screen. For tablet pointers, the range 
of X is defined in the rqvb$w_tablet_width field of the 
QVSS biock; the range of Y is defined in the qvb$w_ 
tablet_height field of the QVSS block. 





new cursor 
position 


X position on physical screen 0 


Y position on physical screen 4 








Field Use 
X position on physical screen X position on the physical screen 
Y position on physical screen Y position on the physical screen 








new pointer 
position 










X position on physical screen 0 
Y position on physical screen 4 


Field Use 


X position on the physical X position on the physical screen 
screen 
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Field Use 


Y position on the physical Y position on the physical screen 
screen 
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qvss block (qvb) 
(qvb_common_structure) 








. 
. 
: 
: 
: 
; 
. 
: 
: 
: 
; 
“ 
: 
: 
; 
: 
: 
: 
: 
. 
. 
: 
. 


(Continued on next page) 
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Example 5-5 (Cont.) Calling Program for Example Subroutines 


QVB$L_UNIT_NUMBER 
QVB$L_POINTER_SETUP 





104 
108 


QVB$W_HOLD_DEFER_CNT 


The following list describes the contents of each field in the QVSS block. 


The names in the following fields of the preceding data structure have 
the prefix QVB$B_. The prefixes are omitted in the diagram so the field 
names fit within the fields. 


DEVICE_TYPE 
BITS_PER_PIXEL 
SPARE_B_1 
CURSOR_PLANES 


Field 


QVB$L_VIDEOSIZE 
QVB$L_VIDEOADDR 
QVB$L_MAPSIZE 
QVB$L_MAPADDR 
QVB$L_CONTEXT 
QVB$L_CSR 
QVB$W_MOUS_XPIX 
QVB$W_MOUS_YPIX 
QVB$W_WIDTH 
QVB$W_HEIGHT, 
QVB$W_X_RESOL 
QVB$W_Y_RESOL. 
QVB$L_MOUS_XABS 


QVB$L_MOUS_YABS 
QVB$L_MAIN_VIDEOSIZE 
QVB$L_MAIN_ 


VIDEOADDR 
QVB$L_MAIN_MAPSIZE 
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Use 


Full size of video memory, in bytes (QVSS specific). 
Address of ist byte of video memory (QVSS specific). 
Size of scanline map, in words (QVSS specific). 
Address of scanline map (QVSS specific). 
Reserved for use by Digital. 

Reserved for use by Digital. 

X coordinate of the current pointer position. 

Y coordinate of the current pointer position. 
Maximum horizontal size of screen, in pixels. 
Maximum vertical size of screen, in pixels. 
Horizontal pixels per inch of physical screen. 
Vertical pixels per inch of physical screen. 


Pointer X position on signed 32-bit virtual coordinate 
space. Used to obtain relative motion when cursor 
hardware tracking not used. 


Pointer Y position on signed 32-bit virtual coordinate 


Space. 


Size of video memory allocated to the windowing 
system, in bytes (QVSS specific). 


Address of video memory allocated to the windowing 
system (QVSS specific). 


Size of the windowing system scanline map (QVSS 
specific). 
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Field 


QVB$L_MAIN_MAPADDR 
QVB$W_MAIN_MAPMIN 


QVB$W_MAIN_MAPMAX 


QVB$L_ 
CHARACTERISTICS 


QVB$W_SCRSAV_ 
TIMOUT 


QVB$W_BUTTONS 


QVB$W_KEYCLICK_ 
VOLUME 


QVB$W_TABLET_XPIX 
QVB$W_TABLET_YPIX 
QVB$W_TABLET_WIDTH 


QVB$W_TABLET_ 
HEIGHT 


QVB$W_BUT_STATUS 


QVB$B_BITS_PER_PIXEL 


QVB$B_DEVICE_TYPE 
QVB$W_FLAGS 


QVB$B_CURSOR_ 
PLANES 


QVB$B_SPARE_B_1 
QVB$W_SPARE_W_1 
QVB$W_TABLET_XSIZE 


Use 


Address of the windowing system scanline map (QVSS 
specific) 


Entry number of the lowest entry in the scanline map 
last updated (QVSS specific). 


Entry number of the highest entry in the scanline map 
last updated (QVSS specific). (Updating these fields 
permits the driver to update only the modified portion 
of the scanline map, using the main windowing system 
scanline map area.) 


Current systemwide windowing characteristics. 
Current screen saver timeout value, in seconds. 


This field no longer supported. 


Default keyclick volume. Value must be in the range of 
1 to 8 (1 is loudest). Default is 3. 


Current X position on a tablet, in pixels. 
Current Y position on a tablet, in pixels. 
Maximum horizontal size of a tablet, in pixels. 
Maximum vertical size of a tablet, in pixels. 


Current up/down status of the pointing device buttons. 
If a bit is set, the button is down. The bit positions 
correspond to the button numbers. That is, the select 
button, (number 1) is represented by the first bit, and 
so on. 


Number of bits per pixel. Black and white systems have 
a value of 1. Color systems may be 4 or 8. 


Value identifying driver: 0 for QVSS, 1 for QDSS. 
Internal flags. The following fields are defined in 
QVBS$W_FLAGS: 

Field Use 


QVB$V_TABLET _ This field is one bit long and starts 
at bit 18; indicates that tablet 
is present; 0 equals pointer is 
present. 


QVB$V_STYLUS _ This field is one bit long and starts 
at bit 19; indicates that tablet 
stylus is present. 


The number of planes in the hardware cursor. A color 
cursor has two planes. 


Reserved to Digital. 
Reserved to Digital. | 
Width of tablet, in centimeters (integer value). 
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Field 


QVSS/QDSS Data Structures 


Use 


QVB$W_TABLET_YSIZE 


QVB$F_TABLET_XRATIO 
QVB$F_TABLET_YRATIO 
QVB$L_UNIT_NUMBER 


QVB$L_POINTER_ 
SETUP 


QVB$W_HOLD_DEFER_ 
CNT 


Height of tablet, in centimeters (integer value). 


Floating-point ratio of screen width to tablet width, in 
pixels. 


Floating-point ratio of screen height to tablet height, in 
pixels. 


Number of the video device unit associated with the 
QVB. 


System characteristics. Contains the current status 
for system wide pointer characteristics. The following 
fields are defined within QVB$L_POINTER_SETUP: 


Field Use 

QV$V_PTR_LEFT_ Indicates pointer is left handed 
HAND if bit is set. 

QV$V_PTR_ Indicates tip of stylus is select 


INVERT_ STYLUS button if bit is set. 


Reserved for use by Digital. 


The following constants are defined in conjunction with the QDB$. 


Value 


Constant 


KEY$C_SELECT 
KEY$C_BUTTON_1 
KEY$C_BUTTON_2 
KEY$C_BUTTON_3 
KEY$C_F1 
KEY$C_F2 
KEY$C_F3 
KEY$C_F4 
KEY$C_F5 
QVB$C_QVSS 
QVB$C_QDSS 
QVB$C_LENGTH 
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Select button 

Pointer device button 1 

Pointer device button 2 

Pointer device button 3 

Function key F1 

Function key F2 

Function key F3 

Function key F4 

Function key F5 

QVSS driver type constant (= 0) 
QDSS driver type constant (= 1) 
Length of the QVB structure 
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reserved function 
keystroke ast 
specification 
block 


AST service routine address 














0 
AST parameter 4 
! 
input token address 12 
Field Use 
AST service routine AST service routine address is 0 if no AST action 
address routine is required. 
AST parameter The user-defined AST parameter is delivered to the 
AST action routine. It is not examined by the driver. 
Access mode The access mode to deliver the AST is maximized with 


the current access mode. 


Input token address This address of a longword receives an input token 
when an AST routine is called. Word 0 of the longword 
contains token data defined by the $SMGDEF macro 
for these function keys. By default an AST is only 
signaled on a down transition. 





screen rectangle 
values block 


MINX (left side value) 










0 
eee id 
ee 
ee 


Field Use 

MINX (left side value) Pixel value for left side of rectangle. 
MINY (bottom side value) Pixel value for bottom side of rectangle. 
MAXX (right side value) Pixel value for right side of rectangle. 
MAXY (top side value) Pixel value for top side of rectangle. 
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system 
characteristics 
block 









Field Use 





Enabled characteristics The first longword is a mask of characteristics to be 
mask enabled. 


Disabled characteristics The second longword is a mask of characteristics to be 


mask disabled. 


The system characteristics, defined by the $QVBDEF 
macro, consist of the following bits: 


Characteristic 


QV$M_KEY_ 
AUTORPT 


QV$M_KEY_ 
KEYCLICK 


QV$M_KEY_UDF6 


QV$M_KEY_UDF 11 


QV$M_KEY_UDF 17 


QV$M_KEY_ 
UDHELPDO 
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Default Meaning 


On. 


On 


Off 


Off 


Off 


Off 


Key held down 
automatically repeats. 


Keyclick sounds on 
each keystroke. 


Function keys F6 
through F10 generate 
up/down transitions. 


Function keys F11 
through F14 generate 
up/down transitions. 


Function keys F17 
through F20 generate, 
up/down transitions. 


Function keys HELP 
and DO generate 
up/down transitions. 
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Field 


Keyclick volume 


Screen saver timeout 
value 


Use 


QV$M_KEY_UDE1 


QV$M_KEY_ 
UDARROW 

QV$M_KEY_ 
UDNUMKEY 


QV$M_SYS_ 
SCRSAV 


Off 


Off 


Off 


Function keys E1 
through E6 generate 
up/down transitions. 


Arrow keys generate 
up/down transitions. 


Numeric keypad keys 
generate up/down 
transitions. 


Disable video output 
to monitor if no input 
activity occurs within 
the number of minutes 
specified in the 
fourth longword. 

Any keystroke, pointer 
button transition, or 
pointer motion will 
reset the timer and 
reactivate a disabled 
screen. 


Must be a value from 1 (loudest) to 8 (softest). Default 


is 3. 


Represents minutes of inactivity that must elapse 
before the screen saver is activated. The value must 
be from 1 to 1440. If a value of 0 is specified, the 
timeout value is not changed. Default is 15. 
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B QDSS-Specific Data Structures 


This appendix illustrates and describes the QDSS data structures 
predefined in the SYSLIBRARY:VWSSYSDEF lan definition file (where 

lan is the file extension for the language you are using). (You choose which 
language definition files are created at system installation time.) 


VWSSYSDEF defines data type structures and constants, including offset 
values that define each field in the structure. Use these predefined offsets 
in your application to access fields. 


This appendix labels each data type with its predefined name and 
each field in the illustrations with its predefined offset. For example, 
VWSSYSDEF defines a structure DOP_STRUCTURE in which it defines 
an offset DOP$W_ITEM_TYPE. Once you associate the storage with a 
structure, you can use the offset to reference the structure. 


To use any predefined constants and offsets, ‘‘include’”’ or ‘‘insert’’ the 
SYSSLIBRARY:VWSSYSDEF file in every module where you reference it. 
Become familiar with the way VWSSYSDEF defines the DOP structure for 
the programming language you are using. 





dop queue 
structure 
(req_structure) 













12 


16 


20 


24 


28 
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The following list describes the contents of each field in the Request Queue 


Definition. 
Field Use 
REQ$L_REQUEST_FLINK Pending drawing operation queue header. 
REQ$L_REQUEST_BLINK Previous drawing operation queue header. 
REQ$L_RETURN_FLINK Forward link for the ordinary return queue. 
REQ$L_RETURN_BLINK _ Backward link for the ordinary return queue. 


REQ$L_RETURN_LARGE_FLINK Forward link for the large DOP return queue. 
REQ$L_LRETURN_LARGE_BLINK — Backward link for the large DOP return queue. 
REQ$W_LARGE_DOP_SIZE Size of a DOP returned to the large DOP return queue. 
REQ$W_SMALL_DOP_SIZE Size of a DOP returned to the ordinary return queue. . 
REQ$L_APPLICATION_RESERVED A longword reserved for use by the application. 


The following constants are defined in conjunction with the REQ$. 


Constant Value 

REQ$K_RETURN_ Offset from beginning of structure to return queue. 
OFFSET 

REQ$K_LENGTH Length of the structure. 
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adss block (qdb) 
(qvb_qdss_structure) 


{ QVBDEF$$_QD_COMMON_FILL (120 bytes) | a) 







120 





QDB$L_SYSVP 
QDB$W_ON_SCREEN_Y QDB$W_ON_SCREEN_X 


124 


128 


QDB$W_ON_SCREEN_HEIGHT QDB$W_ON_SCREEN_WIDTH 
QDB$W_SCROLL_Y QDB$W_SCROLL_X 


132 













136 
| 144 
148 
152 
156 


160 


GBBSH_CLIP_SAVE_HEIGHT 


QDB$L_COLOR_COLORS 


168 
172 


QDB$W_FREE_1_Y QDB$W_FREE_1_X 


176 


QDB$L_COLOR_RBITS 
QDB$L_COLOR_GBITS 
QDB$L_COLOR_BBITS 







204 


QDB$L_COLOR_IBITS 
QDB$L_COLOR_RES_INDICES 
QDB$L_COLOR_REGEN 


208 


212 


(Continued on next page) 
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Example 5-5 (Cont.) Calling Program for Example Subroutines 


QDB$L_COLOR_MAPS 
QDB$L_COLOR_INTENSITY_FLAG 






216 


220 


The following list describes the contents of each field in the QDSS block. 
Note that the first part of the QDB is actually the QVB. See Appendix A for 
a full explanation of the OVB fields. 


Field 

QVBDEF$_QD_ 
COMMON_FILL 
QDB$L_SYSVP 
QDB$W_ON_SCREEN_X 


QDB$W_ON_SCREEN_X 


QDB$W_ON_SCREEN_ 
WIDTH 


QDB$W_ON_SCREEN_ 
HEIGHT 


QDB$W_SCROLL_X 
QDB$W_SCROLL_Y 


QDB$W_SCROLL_WIDTH 


QDB$W_SCROLL_. 
HEIGHT 


QDB$W_FREE_1_X 
QDB$W_FREE_1_Y 


QDB$W_FREE_1_WIDTH 


QDB$W_FREE_1_ 
HEIGHT 


QDB$W_FONT_X 
QDB$W_FONT_Y 


QDB$W_FONT_WIDTH 
QDB$W_FONT_HEIGHT 
QDB$L_COLOR_INDICES 


Use 

The part of the block occupied by the QVB Common 
block. 

Systemwide viewport ID. 


X coordinate of the lower left-hand corner of onscreen 
memory. 


Y coordinate of the lower left-hand corner of onscreen 
memory. 


Width of onscreen memory. 
Height of onscreen memory. 


X coordinate of the lower left-hand corner of the scroll 
area. 


Y coordinate of the lower left-hand corner of the scroll 
area. 


Width of the scroll area. 
Height of the scroll area 


X coordinate of the lower left-hand corner of writable 
memory. 


Y coordinate of the lower left-hand corner of writable 
memory. 


Width of writable memory. 
Height of writable memory. 


X coordinate of the lower left-hand corner of bitmap 
storage area. 


Y coordinate of the lower left-hand corner of bitmap 
storage area. 


Width of the bitmap storage area. 
Height of the bitmap storage area. 
Color map size. 
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Field Use 
QDB$L_COLOR_ Maximum number of possible colors. 
COLORS 


QDB$L_COLOR_RBITS Number of bits of precision for red. 
QDB$L_COLOR_GBITS Number of bits of precision for green. 
QDB$L_COLOR_BBITS Number of bits of precision for blue. 


QDB$L_COLOR_IBITS Number of bits of intensity precision. . 
QDB$L_COLOR_RES_ Number of color map entries reserved by the system. 
INDICES 


QDB$L_COLOR_REGEN Color regeneration characteristics. On a QDSS system 


color regeneration is retroactive. 
QDB$L_COLOR_MAPS Number of hardware color maps (always 1 for QDSS). 


QDB$L_COLOR_ Indicates color (0) or intensity (1) mode. 
INTENSITY_FLAG 


The following constants are defined in conjunction with the QDB. 


Constant Value 


QVB$C_LENGTH Length of the QVB structure. 





return queue 
structure 
(ret_structure) 








RET$L_RETURN_FLINK 
RET$L_RETURN_BLINK 


RET$L_RETURN_LARGE_FLINK 


RET$L_RETURN_LARGE_BLINK 


RET$W_LARGE_DOP_SIZE RET$W_SMALL_DOP_SIZE 
RET$L_APPLICATION_RESERVED 


12 


16 


20 
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The following list describes the contents of each field in the request queue 
definition. 





Field Use 





RET$L_RETURN_FLINK Forward link for the ordinary return queue. 
RET$L_RETURN_BLINK Backward link for the ordinary return queue 


RET$L_RETURN_ Forward link for the large DOP return queue. 
LARGE_FLINK 

RET$L_RETURN_. Backward link for the large DOP return queue. 
LARGE_BLINK 

RET$W_LARGE_DOP_ Size of a DOP returned to the large DOP return queue. 
SIZE 

RET$W_SMALL_DOP_ Size of a DOP returned to the ordinary return queue. 
SIZE 

RET$L_APPLICATION_ Longword reserved for use by the application. 
RESERVED 





transfer 
parameter 
block (tpb) 
(tpb_structure) 













12 





16 


20 
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The following list describes the contents of each field in the Transfer 


Parameter block. 


Field 
TPBS$B_TYPE 


TPB$B_SIZE 
TPB$W_X_SOURCE 
TPBS$W_Y_SOURCE 
TPB$W_WIDTH 
TPB$W_HEIGHT 
TPBS$W_X_TARGET 


TPBSW_Y_TARGET 


TPBSW_X_TARGET_ 
VEC1 


TPBSW_Y_TARGET_ 
VEC1 


TPB$W_L_TARGET_ 
VEC1 


TPBSW_X_TARGET_ 
VEC2 


TPB$W_Y_TARGET_ 
VEC2 


TPB$W_L_TARGET_ 
VEC2 
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Use 


Type of transfer being performed, either bitmap-to- 
processor (BTP), processor-to-bitmap (PTB), or bitmap- 
to-bitmap. Use the constants defined later to load this 
field. 


Reserved to Digital. 

X coordinate of lower left-hand corner of source bitmap. 
Y coordinate of lower left-hand corner of source bitmap. 
Width of source bitmap. 

Height of source bitmap. 


X coordinate of lower left-hand corner of target bitmap. 
(Only specified for bitmap-to-bitmap transfer.) 


Y coordinate of lower left-hand corner of target bitmap. 
Reserved to Digital. 


Reserved to Digital. 
Reserved to Digital. 
Reserved to Digital. 
Reserved to Digital. 


Reserved to Digital. 


QDSS-Specific Data Structures 


The following constants are defined in conjunction with the TPB. 


Constant Value 


TPB$C_BITMAP_XFR Used to specify a bitmap-to-bitmap transfer. 


TPBS$C_SOURCE_ Used to specify a BTP or PTB transfer. 

ONLY ; 
TPB$C_SOURCE_ Structure length for BTP or PTB transfers 
LENGTH 

TPB$C_BITMAP_XFR__—_ Structure length for a bitmap-to-bitmap transfer. 
LENGTH 

TPB$C_LENGTH Full structure length. 





update region 
definition block 
(urd_structure) 





URD$W_Y_MIN URD$W_X_MIN 
URD$W_Y_MAX URD$W_X_MAX 
URD$W_Y_BASE URD$W_X_BASE 


The following list describes the contents of each field in the update region 
definition block. 









Field Use 

URD$W_X_MIN Viewport-relative X coordinate of the lower 
left-hand corner of defined region. 

URD$W_Y_MIN Viewport-relative Y coordinate of the lower 
left-hand corner of defined region. 

URD$W_X_MAX Viewport-relative X coordinate of the upper 
right-hand corner of defined region. 

URD$W_Y_MAX Viewport-relative Y coordinate of the upper 
right-hand corner of defined region. 

URD$W_X_BASE “Absolute X coordinate from lower left-hand 
corner of defined region. 

URD$W_Y_BASE Absolute X coordinate from lower left-hand 


corner of defined region. 
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The following constants are defined in conjunction with the URD. 


Constant Value 
URD$C_ Length of the structure. 
LENGTH 
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QDSS Writing Modes 


This appendix lists all QDSS writing modes and describes the logical 
operations that can be performed when two graphic objects intersect. This 
operation occurs among the destination, the bits composing the existing 
bitmap pixel, and the source index, a value selected by the application in the 
DOP structure. The results of this operation are tested against foreground 
and background color to determine bit settings for the pixels that compose 


the intersecting area. 


The writing mode names are acronyms that reflect the function performed. 
To interpret (and remember) the names, read D for destination, S for 
source index, N for NEGATE, A for AND, O for OR, and X for XOR—with 
all expressions written in reverse Polish notation. 


Table C-1 lists QDSS writing modes and their functions. 


Table C-1 QDSS Writing Modes 


QDSS Writing Modes Function 

WRIT$C_ZEROES All resulting bits are set to 0. 

WRIT$C_DSON The destination is ORed with source index, then the 

. result is negated. - 

WRIT$C_DNSA The destination is negated, then ANDed with the 
source index. 

WRIT$C_DN The destination is negated. 

WRIT$C_DSNA The source index is negated, then ANDed with the 
destination. 

WRIT$C_SN The source index is negated. 

WRIT$C_DSX The destination is XORed with the source index. 

WRIT$C_DSAN The destination is ANDed with the source index, 
then the result is negated. 

WRIT$C_DSA The destination is ANDed with the source index. 

WRIT$C_DSXN The destination is XORed with the source index, 
then the result is negated. 

WRIT$C_S The result is equal to the source index. 

WRIT$C_DNSO The destination is negated, then ORed with the 
source index. 

WRIT$C_D The result is equal to the destination. 

WRIT$C_DSNO The source index is negated, then ORed with the 
destination. 

WRIT$C_DSO The destination is ORed with the source index. 

WRIT$C_ONES All resulting bits are set to 1. 
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In addition, you can specify the following modifiers with the writing modes (by ANDing the two 
values). 


Table C-2 QDSS Writing Mode Modifiers 


Modifier Function 
WRIT$M_USE_MASK_2 Specifies that the mask specified in the DOP bitmap 


ID field be used to determine whether the resulting 
pixel should be written. 


WRIT$M_COMP_MASK_2 Specifies that the complement of the mask specified 
in the DOP bitmap ID field be used to determirie 
whether the resulting pixel should be written. 


WRIT$M_NO_SRC_COMP Specifies that the complement of the source index 
should not be used in the logical operation. 
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QVSS Programming Example 





Programming 


This appendix contains a sample application program for the QVSS driver. 


Program Functions 


The test program in Section D.1.2 shows how a typical program might be 
designed for the QVSS driver. This simple program uses most of the QIO 
functions available to the QVSS driver to perform the following operations: 


1 


on oun Ff 


Sets system windowing characteristics. 


a. Enables autorepeat and keyclick; disables keys F6 to F10 and the 
arrow keys from generating up-transition ASTs. 


b. Sounds the bell to indicate that the characteristics have been set. 


Sets up permanent cursor pattern and a new default system cursor 
pattern. 


Sets up two separate cursor regions on the screen. 

a. Block-shaped cursor is located in the lower left corner. 

b. Cross-shaped cursor is located in the upper right corner. 

Sets up two one-shot requests on keyboard channel 1. 

Sets up keyboard region 1 to be a French keyboard. 

Sets up a private two-stroke compose table for keyboard region 1. 
Sets up a private three-stroke compose table for keyboard region 1. 
Sets up two keyboard regions. 

a. Each region specifies a keyboard AST and a control AST. 


b. The keyboard AST specified for each region performs the following 
actions: 


— Sends an acknowledgment message to the terminal. 
— Sends (echoes) the character typed to the terminal. 


— Ifthe character is a ‘’C,” issues a cycle QIO on the keyboard 
list, which activates the other keyboard region; then delivers a 
control AST for the new region. 


— Ifthe character ‘’F” is typed, sets event flag 2, which terminates 
the program. 


c. The control AST specified for each region sends a message to the 
terminal, indicating that a control AST was delivered. 
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10 


11 


12 


13 
14 


Enables an AST region for pointer buttons. 


a. Sets up an AST to be called each time a pointer button is 
pressed/released in the specified region. | 


b. The AST routine determines which button was changed and prints 
a message identifying the pointer button. The AST routine then 
determines whether the button is currently up or down and prints a 
message to that effect. 


Enables AST for function key F5; sets up an AST to be called each time 
function key F5 is pressed. 


— The F5 AST routine issues a cycle QIO on the keyboard list. 


— The cycle QIO delivers the control AST for the new keyboard 
region. 


Enables an AST region for pointer motion. 


a. Sets up an AST to be called each time the pointer moves within a 
specified region. 


b. Enables the AST routine to print a message indicating that the 
pointer has moved. 


Simulates keyboard input on keyboard channel 2; simulates the input 
of a character string on keyboard region 2. 


Waits for event flag 2 to be set. 


Exits program when event flag 2 is set. 


QVSS Program Example 


TITLE QVSS PORT DRIVER TEST PROGRAM 


-IDENT /02/ 


CHK KI KKK KKK IK KK KER EK KRE KK RK RE KKK IKKE KKK KKK KE KKEKKEKKEKEKEKKKKKKKKKKKEKRK 


SRR KRI KK KEKE KK IKKE KEKE KKEKHE KK KIRKE KKK KER KER ERK KKK KEKR KKK KEKE KKEKHAKKKKKEKKKKKKEK 


v 

: 

? QVSS PORT DRIVER TEST PROGRAM 
f 

' 


-SBTTL DECLARATIONS 


; Define symbols 


$I1ODEF 
SOVBDEF 
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: Define I/O function codes 
; QVSS definitions 


SASSIGN_S DEVNAM=WS_DEVNAM, - 


BLBS 
BRW 


~e ~e ~e ~e ~e ~e ~e 


~e ~e Ne 


~e 


~e 
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and channel number storage 


; Logical name of workstation 


Channel 
Channel 
Channel 
Channel 
Channel 
Channel 
Channel 


Channel 


number storage 
number storage 
number storage 
number storage 
number storage 
number storage 
number storage 


number storage 


State of buttons 


Current 


pointer X,Y coordinates 


Keyboard character 


IOSB descriptor 


MAIN ROUTINE 


START PROGRAM 


, 
+ Allocate workstation descriptor 
a? 
WS_DEVNAM: 

-ASCID /SYSSWORKSTATION/ 
SYS_CHAN1: 

- BLKW 1 
CUR_CHAN1: 

.- BLKW 1 
CUR_CHAN2 : 

. BLKW 1 
KBD_CHAN1: 

- BLKW 1 
KBD_CHAN2: 

» BLKW 1 
BUT_CHAN: 

« BLKW 1 
MOUSE_ CHAN: 

» BLKW 1 
FNKEY_F5_CHAN: 

-BLKW 1 
BUTTON: 

- BLKL 1 
MOUSE_XYs 

-BLKL 1 
CHARACTER: 

-BLKL 1 
DESC: «LONG 2 

- LONG CHARACTER 
IOSB_BLOCK: 

.- QUAD (6) 
DESC1: .LONG 1 

- LONG IOSB_BLOCK+4 

-SBTTL START - 
s++ 
‘ : 
; FUNCTIONAL DESCRIPTION: 
? 
? 
; 
; 
? 
; 
; 
, 
: INPUT PARAMETERS: 
; _ NONE 
a 
; OUTPUT PARAMETERS: 
: NONE 
; 
Yt 
; 
START: 

« WORD 


CHAN=SYS_CHAN1 


RO, 55 
ERROR 


me Ne Ne Ne NO 


KKK IKK AHHH KI KK I KK IK IK IKK IKI KK IKKE KEK KEKE KKKKKEKKEKEKEKEKKKAKKKKK KK KKK KKK IK 


KAKI HK IKI IIH HIK KIKI KEK IKE KEKE KKK KKK KEK KKEKKKRKKKKKK KKK KKK KKK KR KKK KI KK 


Entry mask 
Assign channel using 
logical name and channel number 
Check for success 
Report error on failure 
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5$: BSBW SET_CHARACTERISTICS 
BSBW SET_PERM_CURSOR 
BSBW SET_CURSOR 
BSBW SET_ONESHOT 
BSBW SET_FRENCH_KB 
BSBW SET_COMPOSE2_TABLE 
BSBW SET_COMPOSE3_ TABLE 
BSBW SET_KBDAST 
BSBW SET_BUTTONAST 
BSBW SET_FNKEYAST 
BSBW SET_MOUSEAST 
BSBW SIMULATE_INPUT 
$CLREF_S EFN=# 2 
$WAITFR_S EFN=#2 


Set up system characteristics 

Set up new system wide cursor pattern 
Set up cursors 

Set up one-shot on keyboard channel 1 
Set up French keyboard on keyboard 1 
Set up 2-stroke compose table on kbd 1 
Set up 3-stroke compose table on kbd 1 
Set keyboard AST 

Set up button region AST 

Set up function key AST 

Set up pointer region AST 

Simulate input on keyboard 2 

Clear event flag #2 

Wait for event flag #2 


me we Ne we Ne Ne Ne Se SO NO NO NO Ne Ne 


ERROR: $EXIT_S RO 


-SBTTL SET_CHARACTERISTICS - SET SYSTEM WINDOWING CHARACTERISTICS 


+ 
+ 


FUNCTIONAL DESCRIPTION: 


Set a couple of SYSTEM windowing characteristics and sound the 
bell after they are set. 


INPUT PARAMETERS: 
NONE 


OUTPUT PARAMETERS: 
NONE 


~e we “eae se se Oe we MO Ne Ne Ne Se Ne TO NO 


SET_CHARACTERISTICS: 

MOVL #10$C_QV_MODIFYSYS, RO 

S$QIOW_S CHAN=SYS_CHAN1,- 
FUNC=#10$_SETMODE, - 
Pl = (RO),- 
P4 = #CHAR_BLOCK 

BLBS RO, 10$ 

BRW ERROR 


Modify characteristics code 
Use system channel 

QIO function code 

QVSS function code 
Characteristics block 

Check for success 


se we =e we we Ne 


Sound code 


“ee 


10$: MOVL #IO$C_QV_SOUND, RO 
$QIOW_S CHAN=SYS_CHAN1,- 
FUNC=#10$_SETMODE, - 
Pl = (RO),- 
P2 = #QVSM_SOUND_BELL 
BLBS RO, 20$ 


Bell sound modifier 
Check for success 


~e ™e Me 


BRW ERROR Report error on failure 
2083 RSB 
CHAR_BLOCK: ¢ Characteristics block 


-LONG <QVSM_SYS_AUTORPT!QV$M_SYS_KEYCLICK> 
-LONG <QVSM_SYS_UDF6!QVSM_SYS_UDARROW> 
-LONG §5 

- LONG 30 


Enable these 
Disable these 
Keyclick volume 
Screen saver timeout 


=e se 48 NO 
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-SBTTL SET_PERM_CURSOR - SET UP NEW SYSTEM CURSOR 


+ 
+ 


NONE 


NONE 


Ul we ~e se we Ne we Ne Ne Ne Ne Ne Ne Ne Ne 


ET_PERM_CURSOR: 
MOVL 


SQIOW_S 


BLBS 
BRW 
10S: RSB 


MOUSESBM: 
«WORD 
. WORD 
. WORD 
«WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
MOUSESHOTSPOT: 
. LONG 
. LONG 


 ~e we 


PENCIL: .WORD 
«WORD 
«WORD 
«WORD 
«WORD 
» WORD 
» WORD 
» WORD 
» WORD 
» WORD 
- WORD 
- WORD 
» WORD 
- WORD 
» WORD 
- WORD 


PENCIL_HS: 
.LONG 0 


-LONG 15 


FUNCTIONAL DESCRIPTION: 


INPUT PARAMETERS: 


OUTPUT PARAMETERS: 


#<IO$C_QV_SETCURSOR - 


Set a new system wide cursor pattern. 


; Define system cursor 


!IOSM_QV_LOAD_DEFAULT>,RO ; Default modifier 


CHAN=SYS_CHAN1,- 


FUNC=#10$_SETMODE, - 


Pl =(RO),- 
P2=#MOUSESBM, - 
P4=#MOUSESHOTSPOT 
RO,10S 

ERROR 


“~b0000001110000000 
*~b0000011000000000 
“~b0000001100000000 
“~b0000000110000000 
“60011111111111100 
“~b0100000000000010 
“b1101100110011011 
“b1101100110011011 
461101100110011011 
“b1100000000000011 
“~b1100000000000011 
*b1111000000001111 
“b1100110000110011 
*b0110001111000110 
“b0011010000101100 
“b0001111111111000 


9 
0 


AX0000 
AX0000 
AX0700 
AX0880 
AX0880 
AX1700 - 
AX1100 


‘~X2200 


AX2200 
“~X4400 
“X4400 
“Xc800 
AXf£000 
“axe000 
“xc000 
“xX8000 


Cursor description 
Cursor hot spot 

Check for success 
Report error on failure 


~e se Ne Ne 


Bitmap definition of 
pointer cursor used in call 


~e se 


3 Pointer hot spot definition 


The following two cursor patterns (although not used by the appliation) 
are provided to show alternative patterns 


+ Pencil cursor definition 


3 Pencil hot spot definition 
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QVSS Programming Example 


SPRAYCAN: 
. WORD 
«WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
. WORD 
SPRAYCAN_HS: 
.LONG 0 
.LONG 1 


AX8000 
AX2000 
AX8b00 
AX2780 
“AX8580 
AX0fcO0 
“X0840 
AX09c0 
“~X0940 
“X09c0 
“~X0940 
AX09c0 
“X09c0 
AX0840 
“~X0840 
AXO0fcO, 


e 
a 


, 


Spraycan cursor definition 


Spraycan hot spot definition 


-SBTTL SET_CURSOR - SET UP CURSOR REGIONS 


++ 


NONE 


NONE 


° 
ti 
° 
? 
e 
, 
e 
, 
e 
! 
° 
‘ 
° 
a 
° 
‘ 
. 
, 
. 
] 
e 
, 
° 
t 
e 
f 
° 
? 


ET_CURSOR: 


SASSIGN_ 


BLBS 
BRW 
10$: 


BLBS 
BRW 


208% MOVL 


SQIOW_S 


BLBS 
BRW 


3083 MOVL 


SQIOW_S 


BLBS 
BRW 


408: 

REGION1: 
» LONG 
« LONG 
. LONG 
~ LONG 


RSB 
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SASSIGN_ 


FUNCTIONAL DESCRIPTION: 


INPUT PARAMETERS: 


OUTPUT PARAMETERS: 


S DEVNAM=WS_DEVNAM, - 
CHAN=CUR_CHAN1 

RO, 10$ 

ERROR 

S DEVNAM=WS_DEVNAM, - 
CHAN=CUR_CHAN2 

RO, 20$ 

ERROR 


#I1O$C_QV_SETCURSOR, RO 
CHAN=CUR_CHAN1, - 


’ FUNC=#10$_SETMODE, - 


Pl =(RO),- 
P2=#QVSCURSOR1,- 
P6=#REGION1 

RO, 30$ 

ERROR 


#1OSC_QV_SETCURSOR, RO 
CHAN=CUR_CHAN2 , - 
FUNC=#10$_SETMODE, - 
P1=(RO),- 
P2=#QVSCURSOR2, - 
P6=#REGION2 

RO, 40$ 

ERROR 


20 


300 
300 


=e se Ne 


~e Ne Ne se Ne =e “ee Ne ~e se me we 


~e ™e 


Set two cursor regions for the screen. 


Assign one cursor channel using 
logical name and channel number 
Check for success 


Assign another cursor channel using 
logical name and channel number 


Define cursor region code 
On cursor channel 1 


Cursor description 
Cursor region 1 definition 
Check for success 


Define cursor region code 
On cursor channel 2 


Cursor description 
Cursor region 2 definition 
Check for success 


Cursor region 1 definition 
Lower left corner (ADC) 


Upper right corner (ADC) 


REGIONZ2 : 
« LONG 
«LONG 
- LONG 
- LONG 


QVSCURSOR1: 
«WORD 
. WORD 
. WORD 
~ WORD 
«WORD 
« WORD 
» WORD 
«WORD 
. WORD 
. WORD 
. WORD 
WORD 
. WORD 
«WORD 
«WORD 
. WORD 


QVSCURSOR2: 
» WORD 
» WORD 
«WORD 
. WORD 
- WORD 
.« WORD 
-» WORD 
» WORD 
- WORD 
» WORD 
«WORD 
» WORD 
- WORD 
- WORD 
- WORD 
«WORD 
-SBTTL 

++ 


400 
400 
800 
800 


4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b61111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 
4b1111111111111111 


*b0000011110000000 
“b0000011110000000 
“b0000011110000000 
“~b0000011110000000 
“~b0000011110000000 
*b0000011110000000 
“~b0000011110000000 
“b1111111111111111 
4b1111111111111111 
“*b0000011110000000 
“~b0000011110000000 
“~b0000011110000000 
“~b0000011110000000 
“~b0000011110000000 
“~b0000011110000000 
“~b0000011110000000 


° 
, 


QVSS Programming Example 


Cursor region 2 definition 
Lower left corner (ADC) 


Upper right corner (ADC) 


16 * 16 Cursor pattern 1 (solid) 


16 * 16 Cursor pattern 2 (cross) 


SET_ONESHOT - SET UP ONE-SHOT QIO 


FUNCTIONAL DESCRIPTION: 


Set a two ‘one-shot’ keyboard character reads 
on keyboard channel 1 by enabling a keyboard region 


w/o an AST. 


The input goes to the typeahead buffer, 


and the one-shots read it one character at a time. 


NONE 


OUTPUT PARAMETERS: 


NONE 


ET_ONESHOT: 


SASSIGN_S DEVNAM=WS_DEVNAM, - 


BLBS. 
BRW 


' 
, 
, 
; 
; 
' 
, 
' 
c 
3 INPUT PARAMETERS: 
, 
; 
’ 
? 
? 
, 
' 
Ss 


CHAN=KBD_CHAN1 
RO,10S 
ERROR 


e 
ta 
. 
a 
e 
£ 


Assign a keyboard channel using 
logical name and channel number 
Check for success 


QVSS Programming Example 


10$s MOVL 
SQIOW_S 


BLBS 
BRW 


20$: $QIO_S 


BLBS 
BRW 


30$: $QIO_S 


RSB 
P2_BLOCK: 
. LONG 
. LONG 
. LONG 
. LONG 


ONESHOT_ACK: ; 
-ASCID 
- SBTTL 


+ 
+ 


FUNCTIONAL DE 


INPUT PARAMET 
NONE 


OUTPUT PARAME 
NONE 


ET_FRENCH_KB: 


Request that 
for keyboard 


we se we we UY) we we we Se we se we we we we we te Ne te 


MOVL 
SQIOW_S 


BLBS 
BRW 
5S: RSB 
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#IOSC_QV_ENAKB, RO 


~e se 


CHAN=KBD_.CHAN1, - 
FUNC=#10$_SETMODE, - 
P1=(RO),- 

P2=#P2_BLOCK ; 
RO,20$ : 
ERROR 


CHAN=KBD_CHAN1,- 
FUNC=#10$_READVBLK, - 
IOSB = IOSB_BLOCK,- 
ASTADR = ONE_SHOT_AST,- 
ASTPRM = #ONESHOT_ACK, - 
P2. = #10$C_QV_ENAKB 
RO,30$ 
ERROR 


Queue 2 


=e we Ne Se Ne Ne Ne 


CHAN=KBD_CHAN1,- 
FUNC=#10$_READVBLK, - 
IOSB = IOSB_BLOCK, - 
ASTADR = ONE_SHOT_AST,- 
ASTPRM = #ONESHOT_ACK,- 
P2 = #10$C_QV_ENAKB 


we se we Ne Ne 


ooo°o 


Acknowledgment message 
/ONE SHOT RECEIVED ON CHANNEL 1/ 


Enable keyboard region code 
On keyboard channel 1 


AST specification block 
Check for success 


one-shot reads 


QIO Read code 

IOSB block 

AST that reads character 
Acknowledgment message 
Indicates keyboard list 
Check for success 


AST specification block 1 
AST address 

AST parameter 

AST delivery mode 

Input token 


SET_FRENCH_KB - SET UP A FRENCH KEYBOARD 


SCRIPTION: 


ERS: 


TERS: 


the vc driver use the new keyboard 
1. 


#<IO0$C_QV_LOAD_KEY_TABLE>, RO 
CHAN = KBD_CHAN1, - 

FUNC = #I0$_SETMODE, - 

(RO), - 

P2 = #KB_LAYOUT_TBL_LEN, - 

P3 = #KB_LAYOUT_TBL 


~e “ee 


J 
ron 
" 


~e se we 


Set up a French keyboard on keyboard channel 1. 


table as the private table 


Change the keyboard layout 
On keyboard channel 1 


Keyboard table size 
New keyboard table 
Check for success 


~e “se we NO 


~e se we “eo “Oe Ne Ne Ne 


QVSS Programming Example 


Generate a new keyboard table using macros. This table will define 
the layout of the characters on the workstation keyboard. 


VCSKEYINIT KB_LAYOUT_TBL ; Generate the table 


Make any changes to the table here. Because VCSKEYINIT was used to generate 
the table, only the characters that must be changed need to be specified. 

For example, if the "A" key will still be the "A" key in the new layout 

and the various combinations of shift/control/lock are to remain the same, it 
need not be specified again. (Note that the key definitions do not have to 
be in order. 


VCSKEY 1,<“a/!/>,<*xO0BO>,<*x0FF>,<*x0FF>,- 
<a/!/>,<*xOBO>, <*°xOFF>,<*x0OFF> 
VCSKEY 2,<*a/1/>,<“*a/t+/>,<*xOFF>,<*x0OFF>,- 
<4a/1/>,<*a/+/>,<*XOFF>, <*X0OFF> 
VCSKEY 3,<a/2/>,<Aa/"/>,<*x000>,<*x000>,- 
<“a/2/>,<Aa/"/>,<*x000>,<*x000> 
VCSKEY 4,<*a/3/>,<“a/*/>,<*x01B>,<*x01B>,- 
<“a/3/>,<’a/*/>,<*x01B>,<*x01B> 
VCSKEY 5,<%a/4/>,<*x0E7>,<*x01C>,<*x01C>,- 
<a/4/>,<°x0E7>,<*x01C>, <*x01C> 
VCSKEY 7,<*a/6/>,<*a/&/>,<*x01E>,<*x01E>,- 
<*a/6/>,<“a/&/>,<*xO1LE>,<*x01E> 
VCSKEY 8,<*a/7/>,<*x02F>,<*x01F>,<°x01F>,- 
<“a/7/>,<*x02F>,<*x01F>,<*x01F> 
VCSKEY 9,<“a/8/>,<“a/ (/>,<°xO7F>,<*x07F>,- 
<“a/8/>,<*a/(/>,<°x07F>,<*x07F> 
VCSKEY 10,<*a/9/>,<“a/) />,<*x0OFF>,<*x0FF>,- 
' €fa/9/>,<Aa/)/>,<*xOFF>,<*x0OFF> 
VCSKEY 11,<*a/0/>,<*a/=/>,<*x0OFF>,<*x0FF>,- 
<*a/0/>,<a/=/>,<*x0OFF>,<*x0FF> 
VCSKEY 12,<*x081>,<“a/?/>,<*x0OFF>,<*x0FF>,- ; Diacritical (') 
<4x081>,<%a/?/>,<*xOFF>,<*x0OFF> 
VCSKEY 13,<*x082>,<*x083>,<*x01E>,<“xO1E>,- ; Diacriticals (* %) 
<*X082>,<*x083>,<“x0OFF>,<*x0FF> 
VCSKEY 19, <’4a/2z/>,<*a/Z/>,<*x01A>,<*x01A>,- 
<*a/z/>,<“a/Z/>,<*x01A>,<*x01A> 
VCSKEY 24,<*x0E8>,<*xOFC>,<*xOFF>,<“x0FF>, - 
<“°XO0E8>,<“*xOFC>,<*x0OFF>,<*x0OFF> 
VCSKEY 25,<*°x080>,<*x084>,<“*x0FF>,<*x0FF>,- ; Diacriticals (" ~) 
<*x080>,<*x084>,<*x0FF>,<*x0FF> 
VCSKEY 35, <AXxXOE9>, <*x0F6>,<“x0FF>,<*x0FF>,- 
<AXOEQ>, <*xOF6>,<“*xOFF>, <*“xOFF> 
VCSKEY 36 ,<*xOEO>,<*x0E4>,<“x0OFF>,<“x0OFF>,- 
<*“XOEO>, <“xOE4>,<*xOFF> ,<“x0OFF> 
VCSKEY 37,<“a/$/>,<*x0A3>,<*xOFF>,<*xOFF>,- 
<*a/!/>,<*x0BO>,<*x0FF>,<*x0FF> 
VCSKEY 46 ,<*a/,/>,<4a/3/>,<*xOFF>,<“xOFF>,- 
<*a/,/>,<*a/3/>,<*xOFF>,<*xOFF> 
VCSKEY 47,<*a/./>,<*a/3/>,<*xOFF>,<*x0FF>,- 
<Aa/./>,<Aa/3/>,<AxOFF> ,<*x0FF> 
VCSKEY 48,<“a/-/>,<*a/_/>,<°xOFF>, <*x0FF>,-~ 
<Aa/-/>,<“a/_/>,<°xOFF>,<*xOFF> 
VCSKEY 39 ,<“*a/y/>,<*a/Y¥/>,<*x019>,<*x019>,- 
<“a/y/>,<*a/Y¥/>,<*x019>,<*x019> 


VCSKEYEND KB_LAYOUT_TBL_LEN : End the table, 
; and determine its length 
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QVSS Programming Example 


-SBTTL SET_COMPOSE3_ TABLE - SET UP A THREE-STROKE COMPOSE TABLE 


+ 
+ 


INPUT PARAMETERS: 
NONE 


OUTPUT PARAMETERS: 
NONE 


ET_COMPOSE3_ TABLE: 


me we se se [se Se se se Ne we Ne “se Ne Ne we Se Ne Ne 


MOVL #<IO$C_QV_LOAD_COMPOSE_TABLE>, RO 
SQIOW_S CHAN = KBD_CHAN], - 
FUNC = #IOS_SETMODE, - 
Pi = (RO), - 
P4 = #COMPOSE3_TBL_LEN, - ; 
P5 = #COMPOSE3_TBL : 
BLBS RO,5$ ; 
BRW ERROR 
$s 


RSB 


se we se we we we (1 


VCSCOMPOSE_KEYINIT 


Fill the table here. 


~e ~e se 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VC$COMPOSE_KEY 


VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VC$COMPOSE_KEY 
VC$COMPOSE_KEY 


FUNCTIONAL DESCRIPTION: 


COMPOSE3_TBL 


<Aa/A/>,<Aa/"/>,,<*xc4> 
<Aa/A/>,<a/'/>,,<?xel> 
<“a/A/>,<Aa/*/>,.<*xc5> 
<“a/A/>,<*a/A/>,<@> 

<*a/B/>,<“a/E/>, ,<*xc6> 
<“a/B/>,<“a/*/>,.<0xc2> 
<*a/A/>,<*a/_/>,,<*xaa> 
<Aa/A/>,<“4a/*\/>,,<*xc0> 
<“a/A/>,<Aa/~/>,.<*XC3> 
<Aa/A/>,<*x80>, ,<*xc4> 
<“a/A/>,<*xb0>, ,<*xc5> 


<“a/C/>,<*al/l,/>,,<*xC7> 
<Aa/C/>,<“a\/\>, ,<*xa2> 
<Aa/C/>,<4a/0/>, ,<*xa9> 
<*a/C/>,<*a/0/>,,<*xa9> 
<*a/C/>,<*a/|/>,,<*xa2> 


VCSCOMPOSE_KEYEND  COMPOSE3_TBL_LEN 
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’ 


Set up a private three-stroke compose table on keyboard channel 1. 


Request that the VC driver use the new three-stroke compose table as the 
private table for keyboard 1. 


; Change the compose table 
; On keyboard channel 1 


Three-stroke table size 
New three-stroke table 
Check for success 


Generate a new three-stroke compose table. This table will define the new 
compose sequences for a keyboard region (This example shows a subset of 
the standard three-stroke compose sequences - the complete default 
three-stroke table is in Appendix G). 


Generate an empty table 


; Order sensitive 


End the table, 
and determine its length 


QVSS Programming Example 


-SBTTL SET_COMPOSE2_ TABLE ~ SET UP A TWO-STROKE COMPOSE TABLE 


+ 
+ 


INPUT PARAMETERS: 
NONE 


OUTPUT PARAMETERS: 
NONE 


' 
! 


ET_COMPOSE2_TABLE: 


se se se we Uf} se se we Se we we Ne we Se Ne Ne se Ne NO 


MOVL 
SQIOW_S CHAN = 
FUNC = 
Pl = 
P2 = 
P3 = 
BLBS RO,5S_ 
BRW ERROR 
5$: RSB 


we te we Ne MO 


VCSCOMPOSE_KEYINIT 


Diaresis mark 


~e te Se 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 


rr A NOM OD 


~e we we 


VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 


Generate a new two-stroke compose table. 
compose sequences for a keyboard region (This example actually shows the 
default table of two-stroke compose sequences). 


FUNCTIONAL DESCRIPTION: 


KBD_CHAN1, - 
#10$_SETMODE, - 


(RO), ~ 
#COMPOSE2_TBL_LEN, - 
#COMPOSE2_TBL 


<*x80>,<a/ />,<"> 

<*x80>,<“a/A/>, ,<*xc4> 
<*x80>,<‘’a/E/>, ,<“xcb> 
<*x80>,<“a/I/>,,<“xcf> 
<*x80>,<*a/0/>, ,<*xd6> 
<*x80>,<‘a/U/>, ,<*xde> 
<*x80>,<“%a/Y/>,,<*xdd> 
<*x80>,<“a/a/>,,<*xe4> 
<*x80>,<“a/e/>, ,<“xeb> 
<*x80>,<*a/i/>,,<“xef> 
<*x80>,<“a/o/>, ,<*F6> 
<*x80>,<“a/u/>, ,<*xfc> 
<*x80>,<“a/y/>,,<*xfd> 


<*x81>,<a/ />,<'> 

<*x81>,<*a/A/>, ,<*xcl1> 
<*x81>,<*a/E/>, ,<*xc9> 
<*x81>,<‘*a/I/>,,<*xcd> 
<“x81>,<“*a/O/>, ,<*xd3> 
<*x81>,<“a/U/>, ,<*xda> 
<“x81>,<“a/a/>, ,<“xel> 
<°x81>,<*a/e/>, ,<*xe9> 
<4x81>,<a/i/>, ,<*xed> 
<*x81>,<“a/o/>, ,<*xf£3> 
<*x81>,<“a/u/>, ,<*xfa> 


#<IOSC_QV_LOAD_COMPOSE_TABLE>, RO 


e 
? 


ne Ne NO 


Set up a private two-stroke compose table on keyboard channel 1. 


Request that the VC driver use the new two-stroke compose table as the 
private table for keyboard 1. 


; Change the compose table 
On keyboard channel 1 


Two-stroke table size 
New two-stroke table 
Check for success 


This table will define the new 


COMPOSE2_TBL,COMPOSE_2=YES 
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QVSS Programming Example 


++ 


° 
' 
e 
’ 
e 
, 
e 
, 
° 
’ 
° 
U 
° 
‘ 
e 
r 
° 
' 
e 
’ 
° 
U 
® 
‘ 
° 
’ 
e 
q 


10$:3 
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VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 


-VCS$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VC$COMPOSE_KEY 
VC$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


<*x82>,<“a/ />,<*\> 

<4x82>,<“a/A/>, ,<*xc0> 
<*x82>,<a/E/>, ,<*xc8> 
<*°xX82>,<“a/I/>, ,<*xcc> 
<*x82>,<*%a/O/>, -<*xd2> 
<°x82>,<*a/U/>, ,<*xd9> 
<A482>,<a/a/>, ,<*xe0> 
<*x82>,<“a/e/>, ,<*xe8> 
<*x82>,<“a/i/>,,<*xec> 
<*°x82>,<“a/o/>, ,<*xf2> 
<*°x82>,<“a/u/>, ,<°xf£9> 
<*x83>,<a/ />,<> 

<*x83>,<*a/A/>, ,<*xe2> 
<*°x83>,<“a/E/>, ,<*xca> 
<°x83>,<“a/I/>,,<*xce> 
<*x83>,<“a/0/>, ,<*xd4> 
<4x83>,<“a/U/>, ,<*xdb> 
<x83>,<“a/a/>,,<*xe2> 
<*°x83>,<“a/e/>, ,<*xea> 
<*x83>,<%a/i/>,,<“xee> 
<x83>,<%a/o/>, ,<*xf4> 
<°xX83>,<a/u/>, ,<*xfb> 


<4x84>,<%a/ />,<~> 

<*x84>,<“a/A/>, ,<*xc3> 
<*x84>,<“a/N/>, ,<*xd1> 
<*x84>,<%a/0/>, ,<*xd5> 
<*x84>,<“a/a/>, ,<*xe3> 
<*x84>,<“a/n/>,,<*xf1> 
<°x84>,<%a/o0/>,,<*x£5> 
<*x84>,<‘*a/u/>,,<*xfc> 


<*x85>,<a/ />,,<*xb0> 
<“x85>,<‘“a/A/>, ,<*xc5> 
<*x85>,<“a/a/>,,<*xe5> 


VCSCOMPOSE_KEYEND COMPOSE2_TBL_LEN 


° 
, 
. 


‘ 


End the table, 


and determine its length 


-SBTTL SET_KBDAST - SET UP KEYBOARD REGIONS 


FUNCTIONAL DESCRIPTION: 


Enable several keyboard regions. 


INPUT PARAMETERS : 


NONE 


OUTPUT PARAMETERS: 


NONE 


ET_KBDAST: 
SASSIGN_S DEVNAM=WS_DEVNAM, - 
CHAN=KBD_CHAN2 


# LOSC_QV_MODIFYKB, RO 
CHAN=KBD_CHAN1,- 


~e se Ne 


me Ne 


FUNC=#10$_SETMODE, - 


P2=#P2_BLOCK1,- 
P3=#P3_BLOCK 


se se we 


BLBS RO, 10$ 
BRW ERROR 
MOVL 
$QIOW_S 

P1=(RO),- 
BLBS RO,20$ 
BRW ERROR 


Assign keyboard channel 2 using 
logical name and channel number 
Check for success 


Modify the keyboard 
On keyboard channel 1 


AST specification block 
Control AST block 
Check for success 


208: MOVL 


SQIOW_S 


BLBS 
BRW 


308: RSB 


P2_BLOCK1: 
. LONG 
. LONG 
. LONG 
. LONG 
ACK1: -ASCID 
P2_BLOCK2: 
. LONG 
. LONG 
. LONG 
. LONG 


ACK2: -ASCID 


P3_BLOCK: 
. LONG 
. LONG 
. LONG 
. LONG 
-SBTTL 
++ 


NONE 


NONE 


. 
, 
° 
‘ 
e 
, 
. 
f 
. 
r 
. 
? 
. 
‘ 
2 
f 
° 
, 
° 
? 
e 
q 
° 
’ 
e 
? 
° 
f 


ET_BUTTONAST: 


SASSIGN_S DEVNAM=WS_DEVNAM,- 


BLBS 
BRW 


10$ MOVL 


$QIOW_S 


BLBS 

BRW 
2083 RSB 
BUT_BLOCK: 

- LONG 

. LONG 

- LONG 

. LONG 


BUT_REGION: 
. LONG 
. LONG 
. LONG 
. LONG 


QVSS Programming Example 


#IOSC_QV_ENAKB, RO 
CHAN=KBD_CHAN2, - 
FUNC=#1I0$_SETMODE, - 
P1=(RO),- 
P2=#P2_BLOCK2 ,~ 
P3=#P3_BLOCK 


Enable a keyboard 
On keyboard channel 2 


we Ne 


AST specification block 
Control AST block 


~e se Ne 


RO, 305 Check for success 
ERROR 

3} AST specification block 1 
KBD_AST ; Keyboard AST address 
ACK1 ; AST parameter 
0 ; AST delivery mode 
CHARACTER : Input token 


/INPUT ACKNOWLEDGED CHANNEL 1/ ; Acknowledgment 1 
3} AST specification block 2 
KBD_AST 
ACK2 
0 
CHARACTER 
/INPUT ACKNOWLEDGED CHANNEL 2/ 


Control AST specification block 


a 
CTL_AST 7 Control AST address 
0 , ; AST parameter 
0 3 AST delivery mode 
0 ' 3 Must be zero 


£ 
SET_BUTTONAST ~- ENABLE POINTER BUTTON REGION 


FUNCTIONAL DESCRIPTION: 
Enable a pointer button region, and specify an AST address. 


INPUT PARAMETERS: 


OUTPUT PARAMETERS: 


Assign a button channel using 
logical name and channel number 
Check for success 


CHAN=BUT_CHAN 
RO,105 
ERROR 


~e se we 


Enable button transitions 
On the button channel 


#IOSC_QV_ENABUTTON, RO 
CHAN=BUT_CHAN, - 
FUNC=#I0$_SETMODE, - 
P1=(RO),- 
P2=#BUT_BLOCK, - 
P6=#BUT_REGION 


~e we 


AST specification 
Associated button region 


se we we 


RO,20$ Check for success 
ERROR 
; Button AST specification block 
BUT_AST ; AST address 
0 3; AST parameter 
0) * Access mode 
BUTTON ; Button information longword 
+ Button AST region 
20 3} Lower left corner (ADC) 
20 
300 ; Upper right corner (ADC) 
300 
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QVSS Programming Example 


-SBTTL SET_FNKEYAST - ENABLE F5 FUNCTION KEY 


+ 
+ 


FUNCTIONAL DESCRIPTION: 


INPUT PARAMETERS: 
NONE 


OUTPUT PARAMETERS : 
NONE 


~e Ne ~s Se Ne we we tS NO Ne Ne “Oe “eo we 


SET_FNKEYAST: 
SASSIGN_S DEVNAM=WS_DEVNAM, - 
CHAN=FNKEY_F5_CHAN 


se se Ne 


Enable a function key, and specify an AST address. 


Assign function key channel using 
logical name and channel number 
Check for success 


Enable function key 
On function key channel 


AST specification block 
Modifier indicating F5 key 
Check for success 


Function key ast specification block 
AST address 

AST parameter 

Access mode 

Input token 


PRESSED/ ; Acknowledgment message 


BLBS RO, 10S 
BRW ERROR 
108: MOVL #1OSC_QV_ENAFNKEY, RO ; 
$QIOW_S CHAN=FNKEY_F5_CHAN, - ; 
FUNC=#10$_SETMODE, - 
P1=(RO),- 
P2=#FNKEY_BLOCK, - : 
P3=#QVSM_KEY_F5 ? 
BLBS RO, 30S : 
BRW ERROR 
30S: RSB 
FNKEY_BLOCK: : 
-LONG F5_AST ; 
-LONG F5_ACK ; 
- LONG 0 is 
-LONG CHARACTER ; 
F5_ACK: .ASCID /FUNCTION KEY F5 HAS BEEN 
-SBTTL SET_MOUSEAST - ENABLE POINTER MOVEMENT REGION 
++ 


FUNCTIONAL DESCRIPTION: 


INPUT PARAMETERS : 
NONE 


OUTPUT PARAMETERS: 
NONE 


ET_MOUSEAST: 
SASSIGN_S DEVNAM=WS_DEVNAM, - 
CHAN=MOUSE_CHAN 


BLBS RO,10$ 
BRW ERROR 
10$3 MOVL #IOSC_QV_MOUSEMOV, RO 
SQIOW_S CHAN=MOUSE_CHAN, - 
FUNC=#10$_SETMODE, - 
Pl=(R0O),- 
P2=#MOUSE_BLOCK, - 
P6=#MOUSE_REGION 
BLBS RO,20$ 
BRW ERROR 
208: RSB 
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~e Ne =e se Ne 


we Ne Ne 


Enable pointer movement ASTs for a region. 


Assign pointer channel using 
logical name and channel number 
Check for success 


Enable pointer movement 
On pointer channel 


AST specification block 
Associated region 
Check for success 


QVSS Programming Example 


MOUSE_BLOCK: 
.-LONG MOUSE_AST 
»LONG MOUSE_ACK 
-LONG 0 
-LONG MOUSE_XY 


Pointer region AST specification block 
AST address 

AST parameter 

Access mode 

New cursor position 


~e we Ne Ne Ne 


MOUSE_REGION: Pointer region 


‘se we 


» LONG 400 Lower left corner (ADC) 
- LONG 400 

- LONG 800 } Upper right corner (ADC) 
- LONG 800 


MOUSE_ACK: 
-ASCID /POINTER MOVEMENT DETECTED/ ; Acknowledgment message 


-SBTTL SIMULATE INPUT - SIMULATE INPUT ON KEYBOARD 2 


+ 
+ 


FUNCTIONAL DESCRIPTION: 
Simulate keyboard input on keyboard channel 2. 


INPUT PARAMETERS: 
NONE 


OUTPUT PARAMETERS: 
NONE 


“ee “Ne Ne we Se NO Se we Se Ne we Ne Ne NS 


SIMULATE_INPUT: 
MOVL #I0$C_QV_SIMULATE, RO 
$QIOW_S CHAN=KBD_CHAN2,- 

FUNC=#I0$_SETMODE, - 


Simulate keyboard input 
On keyboard channel 2 


~e we 


P1=(RO),- 
P2=#SIM_ACK,- 3 Acknowledgment 
P3=#0 + No pointer repositioning 
BLBS RO,20$ 3 Check for success 
BRW ERROR 
2083: RSB 
SIM_ACK: 


-ASCID /This input SIMULATED on chan 2./ ; Acknowledgment message 


The following code contains all the ASTs specified in the above QIOs 


ee Ne we 


-SBTTL ONE_SHOT_AST - ONE_SHOT AST ROUTINE 
++ 


FUNCTIONAL DESCRIPTION: 
This is the AST routine specified by the ’one-shot’ read QIO. 


INPUT PARAMETERS: 
NONE 


OUTPUT PARAMETERS: 
NONE 


we Ne ™e ~e se te Ne “Oe Ne Ne Ne we Ne NO 


ONE_SHOT_AST: 
- WORD 
PUSHL 4(AP) 3 Send acknowledgment message 
CALLS #1,G*LIBSPUT_LINE 
BLBS RO, 10S 
BRW ERROR 


10$:3 PUSHAL DESC1 
CALLS #1,G*LIBSPUT_LINE 


Send character typed, 
descriptor points to IOSB 


nue Ne 
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RET 


-SBITL MOUSE_AST - POINTER AST ROUTINE 
r++ 


FUNCTIONAL DESCRIPTION: 

This is the AST routine specified by the enable pointer movement QIO. 
INPUT PARAMETERS: 

POINTER_XY - Contains the current X and Y coordinates for the pointer. 


} 
} 

i 

' 

; 

; 

: 

; 

} OUTPUT PARAMETERS: 
: NONE 
j 

i 

; 

M 


OUSE_AST: 
» WORD 
PUSHL 4(AP) 3} Send acknowledgment message 
CALLS #1,G*LIBSPUT_LINE 
BLBS RO, 10$ 
5$: BRW ERROR 


10S: RET 


-SBITL KBD_AST - KEYBOARD AST ROUTINE 
-SBTTL F5S_AST - FUNCTION KEY F5 AST ROUTINE 


+- 
+ 


FUNCTIONAL DESCRIPTION: 


This is the AST routine specified by the enable keyboard QIO and 
by the enable function key F5 QIO. 


INPUT PARAMETERS: 
NONE 


OUTPUT PARAMETERS: 


ous Ne we Ne Ne NO Ne Se WO SO “Ee Ne VO NO 


NONE 
t 
KBD_AST: 
F5_AST: 
«WORD 
PUSHL 4(AP) 3; Send acknowledgment message 
CALLS #1,G*LIBSPUT_LINE 
BLBS RO, 108 
5S: BRW ERROR 
1083 CMPW #KEYSC_F5,CHARACTER 3; Was F5 typed? 
BNEQ 20$ 
BSBW CYCLE_KBD 3 Cycle the keyboard list 
BRB 40S ; and exit 


208: PUSHAL DESC 
CALLS #1,G*LIBSPUT_LINE 
BLBC RO,5$ 


Send character typed 


~e 


CMPB #°A/C/, CHARACTER Was a "C" typed? 


=e 


BNEQ 305 
BSBW CYCLE_KBD + Cycle the keyboard list 
BRB 40$ 
308: CMPB #°A/F/, CHARACTER 3} Was an "F" Typed? 
BNEQ 40$ 


SSETEF_S EFN=#2 Yes, exit program 


~e 


40S: RET 
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-SBTTL CTL_AST - CONTROL AST ROUTINE 


+ 
+ 


FUNCTIONAL DESCRIPTION: 
This is the control AST routine. 


INPUT PARAMETERS: 
NONE 


OUTPUT PARAMETERS: 
NONE 


~e we we ~e Ne “Se Se we SO we Ne Ne WO NO 


CTL_AST: 
» WORD ; 
PUSHAL CYCLE_ACK ; Send acknowledgment message 
CALLS #1,G*LIBSPUT_LINE 
BLBS RO, 105 


5$: BRW ERROR 
108: RET 
CYCLE_ACK: 


-ASCID /KEYBOARD HAS BEEN CYCLED/ ; Acknowledgment message 
-SBTTL BUT_AST - BUTTON AST ROUTINE 


+ 
+ 


FUNCTIONAL DESCRIPTION: 
This is the AST routine specified by the enable pointer movement QIO. 


INPUT PARAMETERS: 
BUTTON —- Status of the pointer buttons. 


OUTPUT PARAMETERS: 
NONE 


se Ne Ne Ne we we Te NO Ne Ne SO Ne Ne Ne 


BUT_AST: 
- WORD 
CMPW #KEY$C_BUTTON_1, BUTTON 
BNEQ 10$ 
PUSHAL BUT1_ACK 


Was BUTTON 1 changed? 
(predefined constant) 


~e Ne 


BRB 50$ 
108: CMPW #KEYSC_BUTTON_2,BUTTON ; Was BUTTON 2 changed? 
BNEQ 208 
PUSHAL BUT2_ACK 
BRB 50$ 
2083 CMPW #KEYSC_BUTTON_3,BUTTON ; Was BUTTON 3 changed? 


BNEQ 100$ 
PUSHAL BUT3_ACK 


50S: CALLS #1,G*LIBSPUT_LINE + Send correct acknowledgment 
BLBS RO,608 
BRW ERROR 
6083 PUSHAL BUTUP_ACK ; Assume button was released 
BBC #31,BUTTON,70$ ; If clear then button released 
PUSHAL BUTDOWN_ACK 3} Otherwise, button was depressed 
708s CALLS #1,G*LIBSPUT_LINE 3 Send acknowledgment message 
BLBS RO, 1005S 
BRW ERROR 


1008: RET 


QVSS Programming Example 


; 
BUT1_ACK: 


-ASCID 
BUT2_ACK: 
.ASCID 
BUT3_ACK: 
.ASCID 
BUTUP_ACK: 
.ASCID 
BUTDOWN_ACK: 
.ASCID 
.SBTTL 


++ 


NONE 


e 
a 
° 
t 
r 
f 
e 
, 
® 
‘ 
° 
f 
° 
, 
° 
f 
° 
Ul 
e 
tf 
° 
c 
r 
, 
° 
, 
° 
ti 


- Acknowledgment messages 


/POINTER BUTTON 1 TRANSITION HAS BEEN DETECTED/ 
/POINTER BUTTON 2 TRANSITION HAS BEEN DETECTED/ 
/POINTER BUTTON 3 TRANSITION HAS BEEN DETECTED/ 
/BUTTON IS UP/ 


/BUTTON IS DOWN/ 
CYCLE_KBD - CYCLE KEYBOARD REGION 


FUNCTIONAL DESCRIPTION: 
This routine cycles the keyboard to the next keyboard region. 


INPUT PARAMETERS: 


OUTPUT PARAMETERS : 


NONE 
YCLE_KBD: 
MOVL #<IOSC_QV_ENAKB! IOSM_QV_CYCLE>,RO ; Use keyboard cycle modifier 
SQIOW_S CHAN=KBD_CHAN1,- ; On keyboard channel 1 
FUNC=#10$_SETMODE, - 
Pl= (RO) 
BLBS RO, 40S 3; Check for success 
BRW ERROR 
408s RSB 
~ END START 
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Keyboard Table Macro 


This appendix contains the macro used to generate a keyboard table. 


-SBTTL VCSKEYINIT ~ Macro to generate keyboard table 


++ 
VCSKEYINIT - Initializes the keyboard table 
VCSKEY - Generates a key table entry for the given position 


This macro defines a given key entry for the keyboard position. 

This entry contains the ASCII translation for the lowercase character, 
uppercase character, control (CTRL) for this position, and shift control 
for this position. In addition it will generate a lock state for this 
position including the character to be used when lock is detected, when 
shift lock is detected, when control lock is detected, and when control 
shift lock is detected. 


se ~e Ne Ne Se Ne Ne NO Ne Ne Ne we NO 


-Macro VCSKEY POSITION, LOWER, SHIFT,CTRL,SHIFT_CTRL, LOCK, - 
SHIFT_LOCK,CTRL_LOCK, SHIFT_CTRL_LOCK 
- =BASE+<<POSITION-1>* 8> 


~BYTE LOWER : Lowercase character 


-IF BLANK, <SHIFT> 
-BYTE LOWER&<*C<1@5>> 
.IFF 

-BYTE SHIFT 

.ENDC 

.IF BLANK,<CTRL> 

- BYTE LOWER&<*C<3@5>> 
IFF 

-BYTE CTRL 

-ENDC 


Shift (uppercase) character 


Control key and character key 


~e 


-IF BLANK,<SHIFT_CTRL> 
BYTE LOWER&<*C<3@5>> 
~lFF 

~BYTE SHIFT_CTRL 
-ENDC 

IF BLANK,<LOCK> 

. BYTE LOWER&<*C<1@5>> 
~IFF 

BYTE LOCK 

-ENDC 


Shift, control and character key 
Usually same as control 


“we me 


Lock and character keys 
Usually the same as shift 


~e Ne 


-IF BLANK, <SHIFT_LOCK> 
» BYTE LOWER&<*C<1@5>> 
-IFF 

- BYTE SHIFT LOCK 

» ENDC 


Shift, lock and character keys 
Usually the same as shift 


ne Ne 


«IF BLANK, <CTRL_LOCK> 

- BYTE LOWER&<*C<3@5>> 
-IFF 

«BYTE CTRL_LOCK 

»ENDC 


Control, lock and character keys 
Usually the same as control 


se Ne 


.IF BLANK,<SHIFT_CTRL_LOCK> 
«BYTE LOWER&<*C<3@5>> 

.IFF 

sBYTE SHIFT_CTRL_LOCK 

. ENDC 


Shift, control, lock & char keys 
Usually the same as control ' 


~e Ne 
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Keyboard Table Macro 


VCSKEY 


VCSKEYINIT NAME, VERSION=1, INTERNAL 
$$$117_ NAME, LONG 


INTERNAL 
2 + * Used for building internal driver table * 


VERSION 


Allocate space for the table. Pre-initialize it to known values (-1). 


»REPEAT MAXKEY-1 


»-ENDM 
-Macro 
- SAVE 
-PSECT 
sIF NB 
elong 
»ENDC 
MAXKEY=49 
TBL_START=. 
NAME==. 
«QUAD 
; 
; 
? 
BASE=. 
. LONG 
« ENDR 
ENDBASE= 


~e wo “e 


VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCS$KEY 
VCSKEY 
VCSKEY 
VCSKEY 
VCS$KEY 
VCSKEY 
VCS$KEY 
VCSKEY 
VCSKEY 


VCSKEY 


-1,-1 


Initialize the table to the North American keyboard. 


1,<*a/*\/>,<%a/~/>,<*x1le>,<*xle>,- 
<“a/*/>,<4a/~/>,<*xle>,<*xle> 
2,<*a/1/>,<“4a/!/>,<*x0OFF>, <4x0FF>,- 
<Aa/1/>,<4a/!/>,<*xOFF>, <*x0FF> 
3,<*a/2/>,<*a/@/>,<*x00>,<*x00>, - 
<4a/2/>,<*a/@/>,<*x00>,<*x00> 
4,<*a/3/>,<“a/#/>,<“x1b>,<x1b>,- 
<4a/3/>,<%a/#/>,<°x1b>,<*x1lb> 
5,<*a/4/>,<*a/$/>,<*x1le>,<“xle>,- 
<’a/4/>,<*a/$/>,<*x1le>,<"xle> 
6 ,<%a/5/>,<a/%/>,<*x1d>,<Axld>,- 
<*a/5/>,<%a/%/>,<*x1ld>,<*x1d> 
7,<a/6/>,<*a/*/>,<*xle>,<“xle>,- 
<*a/6/>,<“a/*/>,<*xle>,<*xle> 
8,<*a/7/>,<*a/&/>,<°x1fi>,<*xlf>,- 
<4a/7/>,<a/&/>,<Ax1lf>,<*x1f> 
9,<4a/8/>,<Aa/*/>,<°x7E>,<x7£>,- 
<“4a/8/>,<a/*/>,<°x7£>,<“°x7f£> 
10,<*a/9/>,<*a/(/>,<*x0OFF>,<*x0FF>,- 
<Aa/9/>,<“a/(/>,<*xOFF>,<*x0FF> 
11,<*a/0/>,<*a/)/>,<*xOFF>,<“x0FF>,- 
<4a/0/>,<a/)/>,<*xOFF>,<*x0FF> 
12,<“%a/-/>,<*%a/_/>,<*x1f£>,<*x1f>,- 
<Aa/-/>,<“a/_/>,<*x1f>,<*x1lf> 
13,<*a/=/>,<*a/+/>,<*xOFF>,<*x0FF>,- 
<Aa/=/>,<“a/+/>,<AxX0FF> ,<“x0FF> 
14,<*a/q/>,<*a/Q/>,<*x11>,<4x11>,- 
1<4X11>,<*x11> 
15, Ansa /s. <“a/W/>,<*X17>,<4x17>,- 
1<4X17>,<*x17> 
16, <An/e/>, <“a/E/>,<*x05>,<*x05>,- 
1<*X05>,<*x05> 
17, <a/r/>, <Aa/R/>,<*X12>,<*x12>,- 
1<°K12>,<*x12> 
18, <Aa/t/>, <4a/T/>,<*K14>,<*x14>,- 
1<*°X14>,<*x14> 
19 <AA/y/>, <“a/Y¥/>,<*X19>,<*x19>,- 
1<*°K19>,<“x19> 
20, <A/u/>; <’a/U/>,<*xX15>,<*%15>,- 
7<*X15>,<*x15> 
21, <Aa/i/>, <Aa/I/>,<*x09>,<*x09>,- 
1<*X09>,<*x09> 
22, <-a/o/>; <’4a/O0/>,<*x0F>,<*x0F>,- 
1<°XOF> , <*xOF> 
23 /<)a/p/>, <“a/P/>,<*x10>,<*x10>,- 
1<*X10>,<*x10> 
24, <a/[/>, <Aa/{/>,<x1lb>,<4x1b>,- 
<a/[/>,<%a/{/>,<*x1b>,<*x1b> 


Keyboard Table Macro 


VCSKEY 25,<*A/]/>,<4a/}/>,<*xld>,<*xld>,- 
<*a/]/>,<a/}/>,<*x1d>,<*xld> 
VCSKEY 26,<“*A/a/>,<*a/A/>,<*x01>,<*x01>,- 
1<*xX01>,<*x01> 
VCSKEY 27, <a/s/>, <“a/S/>,<*%13>,<*x%13>,- 
7<°X13>,<%x13> 
VCSKEY 28, <a/d/>, <“a/D/>,<*x04>,<*x04>,- 
1<*x04>,<*x04> 
VCSKEY 29, <a/f/>, <Aa/F/>,<*x06>,<*x06>,- 
1<*X06>,<“*x06> 
VCSKEY 30 <a/g/>, <Aa/G/>,<*x07>,<*x07>,- 
1<*X07>,<*x07> 
VCSKEY 31, <a/h/>, <“a/H/>,<*x08>,<*x08>,- 
1<*X08>,<*°x08> 
VCSKEY 32 <AA/4/>, <Aa/3/>,<*xXOA>,<*xOA>,- 
1<*xX0A>,<*x0A> 
VCSKEY 33, <ra/k/>, <“a/K/>,<*x0B>,<*x0B>,- 
1<*X0B>,<*x0B> 
VCSKEY 34, <A/1/>, <“a/L/>,<*x0C>,<*x0C>,- 
1<°X0C> ,<*x0C> 

VCSKEY 35,<*x03B>, ehad />,<°XOFF>,<*x0FF>,- 


<*Xx03B>,<“a/:/>,<*xOFF>,<*x0FF> 
VCSKEY 36,<‘*a/'/>,<‘*a/"/>,<*xOFF>,<*x0FF>,- 
<Aa/'/>,<Aa/"/>,<*xOFF>,<“*xOFF> 


VCSKEY 37,<*a/\/>,<‘“a/|/>,<*x1le>,<*xle>,- 
<*a/\/>,<*a/|/>,<*x1le>,<*x1e> 

VCSKEY 38,<*x3c>,<“*x3e>,<*xOFF>,<“x0FF>,- 
<*x3Cc>,<*%x3e>,<*xX0OFF>,<*x0FF> 
VCSKEY 39,<“*A/2/>,<‘*a/Z/>,<*xX1A>,<“x1A>,- 
7,<*xX1A>,<*xK1A> 
VCSKEY 40, <A/x/>, <Aa/X/>,<°X18>,<*x18>,- 
7<4X18>,<*%x18> 
VCSKEY 41, <AA/c/>, <Aa/C/>,<*%x03>,<*x03>,- 
1<°X03>,<*x03> 
VCSKEY 42, <AA/v/>, <Aa/V/>, <*x16>,<*x16>,- 
1<°K16>,<4x16> 
VCSKEY 43, <a/b/>, <“a/B/>,<*x02>,<*x02>,~ 
1<*X02>,<*x02> 
VCSKEY 44, <AA/n/>, <Aa/N/>,<*xOE>,<*x0E>,- 
,<“xOE>,<*xOE> 
VCSKEY 45, <*A/m/>, <Aa/M/>,<*x0D>,<*x0D>,- 


1<4KO0D>,<*x0D> 


VCSKEY 46,<‘a/, />, <Aa/,/>,<°xOFF>,<*x0FF>,- 
<Aa/,/>,<%a/,/>,<°xOFF> ,<*x0OFF> 

VCSKEY 47,<‘’a/./>,<*a/./>,<*xXOFF>,<“x0FF>,- 
<Aa/./>,<Aa/./>,<*XxOFF>,<°x0FF> 

VCSKEY 48,<*x2f>,<*a/?/>,<*x1f>,<°%x1f>,- 
<“x2£>,<a/?/>,<°x1f£>,<*x1f> 


-endm VCSKEYINIT 
»-MACRO VCSKEYEND TABLE_SIZE 


- =ENDBASE ; 


-IF NOT_BLANK TABLE SIZE 
TABLE_SIZE == ENDBASE - TBL_START 
- ENDC 

- RESTORE 

-ENDM ~- VCSKEYEND 


PC points to first byte after table 


;Size of table 
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Compose Table Macros 


This appendix contains the macros used to construct a compose table. 


-SBTTL VCSCOMPOSE_KEYINI - Macro to initialize a compose sequence table 


++ 
+ MACRO VCSCOMPOSE_KEYINI - Macro to initialize a compose sequence table 
‘ 
3 INPUTS 
H NAME = TABLE NAME TO GENERATE 
? COMPOSE_2 = YES - IF THIS IS A 2 CHARACTER COMPOSE TABLE 
; BLANK - IF A 3 CHARACTER COMPOSE TABLE 
; VERSION = TABLE VERSION 
H INTERNAL = YES - IF THIS MACRO IS BEING CALLED TO BUILD INTERNAL TABLE. 
; BLANK - IF THIS MACRO IS BEING CALLED NORMALLY. 
jo 
e 
»Macro VCSCOMPOSE_KEYINIT NAME,COMPOSE_2,VERSION=1, INTERNAL 
«SAVE 
-PSECT $$$118_’NAME’ A 
-IF NB INTERNAL 
- long 2 3; *** Used by driver, NOT for regular table *** 
» ENDC 
NAME==. 
»save $ Save attributes 
-psect $$5$118 ‘NAME’ B ; Go to other psect 
ext_‘name=. 3 Save base address 
-restore 3; Restore attributes 
- LONG VERSION 
-IF NB COMPOSE_2 
i=0 
DIA_TAB_’NAME=. 
erepeat <256/32> 3; Get the diacritical table 
~long 0 
dia_init \i 
i=i+l 
-endr 
» ENDC 
-SBTTL VCSCOMPOSE_KEY - Macro to generate a compose table entry 
p++ 


INPUTS 


~e “se ws “es ~e “ee we ~e we SO 


STR=. 


MACRO VCSCOMPOSE_KEY - Macro to generate a compose table entry 


INPUT_CHAR1 = FIRST CHARACTER OF COMPOSE SEQUENCE 
INPUT_CHAR2 SECOND CHARACTER OF COMPOSE SEQUENCE 
OUTPUT_SIZE SIZE OF THE OUTPUT STRING (optional, 

if omitted, size will be calculated) 
OUTPUT_CHAR = OUTPUT STRING 


i] 


»Macro VCSCOMPOSE_KEY input_charl,input_char2,output_size, output_char 


-BYTE INPUT_CHAR1 
-BYTE INPUT_CHAR2 

. SAVE 

-PSECT $$$118_’NAME’ B 


-IF BLANK <OUTPUT_SIZE> 
- BYTE 1 
» BYTE OUTPUT_CHAR 
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+ 
+ 


MACRO 


~e ~e Ne te we Ne Ne 


++ 
MACRO 


we Ne Se we we te NS 
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INPUTS 


INPUTS 


-IFF 
-ASCIC |OUTPUT_SIZE] 
- ENDC 


«RESTORE 

«WORD STR-NAME 

.IF NB COMPOSE_2 
I=INPUT_CHAR1/32 
J=INPUT_CHAR1-<1*32> 
DIA \I,\I 

-ENDC 

-endm VCSCOMPOSE_KEY 


VCSCOMPOSE_KEYEND - Macro to end a compose table 


TABLE_SIZE ~ (optional) Location to store size of table 


«MACRO VCSCOMPOSE_KEYEND TABLE_SIZE 

- LONG -1 

-IIF NB,COMPOSE_2, DIA_END DIA_TAB_ ‘NAME 
-IF NB TABLE _SIZE 

TABLE_SIZE == .-name 

-psect $$$118_ ’NAME’ B 

TABLE_SIZE == TABLE_SIZE+<.-ext_’name> 

- ENDC 

- RESTORE 

- ENDM VCSCOMPOSE_KEYEND 


If table size requested 
Get size of first psect 
Jump to other psect 

Add in size of this psect 


we se Ne Ne 


-ENDM VCSCOMPOSE_KEYINIT 
-SBTTL MACRO DIA_INIT - Macro to generate diacritical table 


DIA_INIT - Macro to generate diacritical table 
N - OFFSET INTO TABLE 


-MACRO DIA_INIT N 

DIA_'N = 0 

-MACRO DIA OFFSET, BIT_POS _ 

.IIF GT OFFSET-N,.ERROR ; OFFSETS CANNOT BE GREATER THAN DIA_MAX 
DIA_’OFFSET=1@BIT_POS!DIA_‘ OFFSET 

-ENDM DIA 

«MACRO DIA_GEN X 

-LONG DIA_‘X 

-ENDM DIA_GEN 


»MACRO DIA_END LABEL 
. SAVE 

.=LABEL 

X=0 

-REPEAT N+1 

DIA_GEN \x 

X=X+1 

.ENDR 

. RESTORE 

»-ENDM  DIA_END 


- ENDM DIA_INIT 





Default Three-Stroke Compose Table Values 


This appendix contains the macro that is executed to load the default three- 
stroke compose table values. (The default two-stroke table is shown in the 
example in Appendix D) 


VCSCOMPOSE_KEYINIT QVSCOMPOSE3_TABLE 


Sp it See GE ee ee 


me se NO 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
_VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 


VC$COMPOSE_KEY 
VCS$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCS$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCS$COMPOSE_KEY 


VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 


<‘’a/ />,<*a/"/>,<"> 
<Aa/ />,<*a/'/>,<'> 
<Aa/ />,<*a/*/>,.<*xb0> 
<Aa/ />,<*a/*/>,<%> 
<Aa/ />,<*al~/>,<"> 
<Aa/ />,<*xb0>, ,<*xb0> 


<Aa/i/>,<a/!/>,,<*xal> 
<“a/!/>,<a/P/>,,<*xb6> 
<Aa/1/>,<*a/S/>,,<*xa7> 
<Aa/!/>,<“alp/>, ,<*xb6> 
<Aa/!/>,<“a/s/>,,<*xa7> 


<Aa/"/>,<*a/ />,<"> 

<“a/"/>,<*a/A/>, ,<*xc4> 
<‘a/"/>,<Aa/E/>, ,<*xcb> 
<Aa/"/>,<a/I/>,,<xct> 
<“a/"/>,<“*a/O0/>, ,<*xd6> 
<Aa/"/>,<*a/U/>, ,<*xde> 
<Aa/"/>,<Aa/V¥/>,,<*xdd> 
<a/"/>,<“%a/a/>,,<*xe4d> 
<‘a/"/>,<*a/e/>, ,<*xeb> 
<Aa/"/>,<Aa/i/>,,<*xef> 
<Aa/"/>,<“Aa/o/>, ,<*xf6> 
<Aa/"/>,<*a/u/>,,<*xfe> 
<Aa/"/>,<Aaly/>,,<*xfd> 


<Aa/'/>,<*a/ />,<'> 

<“a/'/>,<*a/A/>,,<*xc1> 
<Aa/'/>,<*a/E/>, ,<*xc9> 
<Aa/'/>,<“a/I/>,,<“xed> 
<Aa/'/>,<*a/O0/>, ,<*xd3> 
<Aa/'/>,<a/U/>,,<*xda> 
<Aa/'/>,<Aala/>, ,<*xel> 
<“a/'/>,<*a/e/>,,<*xe9> 
<Aa/'/>,<a/i/>,,<*xed> 
<Aa/'/>,<*a/o/>,,<*xf£3> 
<Aa/'/>,<*a/u/>,,<*xfa> 


<Aa/(/>,<%a/(/>,<[> 
<“a/(/>,<%a/-/>,<{> 


<“a/)/>,<’a/)/>,<]> 
<’a/)/>,<*a/-/>,<}> 


<Aa/*/>,<ra/ />,,<*xb0> 
<*a/*/>,<*a/A/>, ,<?xc5> 
<“a/*/>,<“a/a/>,,<*xe5> 


<Aa/t+/>,<a/+/>,<#> 
<Aa/+/>,<Aa/—-/>,,<*xbl> 


Default Three-Stroke Compose Table Values 


me Ne we 
to) 


~e we we 


2 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 


VCS$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


34567 89 


VC$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 


VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 


VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 


A to 2 


VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 


<Aa/,/>,<*a/C/>, ,<*xe7> 
<*a/,/>,<a/c/>,,<*xe7> 


<fa/-/>,<a/(/>,<{> 

<‘a/-/>,<*a/)/>,<}> 

<“a/-/>,<a/+/>,,<*xbl> 
<Aa/-/>,<*a/L/>, ,<*xa3> 
<Sa/-/>,<*%a/Y¥/>,_,<*xa5> 
<“a/-/>,<a/1/>,,<*xa3> 
<Aa/-/>,<a/y/>,,<*xa5> 


<Aa/./>,<Aa/*/>, ,<*xb7> 


<Aa\/\>,<4a\/\>,<\> 
<“a\/\>,<*x3e>,<\> 
<“a\/\>,<%a/C/>, ,<*xa2> 
<“a\/\>,<%a/0/>, ,<*xd8> 
<“a\/\>,<*a/U/>, ,<*xb5> 
<“a\/\>,<%a/*/>,,<*a/|/> 
<“a\/\>,<*a/c/>,,<*xa2> 
<“a\/\>,<*a/o/>, ,<*xf8> 
<Aa\/\>,<*a/u/>, ,<*xb5> 


<*a/0/>,<*a/C/>, ,<*xa9> 
<*a/0/>,<*a/S/>,,<*xa7> 
<*a/0/>,<*a/X/>,,<*xa8> 
<*a/0/>,<*a/%/>,,<*xb0> 
<%a/0/>,<*a/c/>, ,<*xad> 
<“a/0/>,<a/s/>,,<*xa7> 
<*a/0/>,<“4a/x/>,,<*xa8> 


<“a/1/>,<*a/2/>,,<*xbd> 
<*a/1/>,<*a/4/>,,<°xbe> 
<4a/1/>,<*a/*/>, ,<*xb9> 


<4a/2/>,<“a/*/>,,<*xb2> 
<Aa/3/>,<Aa/*/>, ,<°xb3> 


<*x30>,<“a\/\>,<\> 
<“x3e>,<%x3c>,,<“xab> 


<Aa/=/>,<a/L/>,,<*xa3> 
<“a/=/>,<*a/Y¥/>,,<*xa5> 
<Aa/=/>,<a/1/>,,<*xa3> 
<a/=/>,<a/y/>,,<*xa5> 


<*%x3e>,<*x3e>, ,<“xbb> 
f a 


<a/?/>,<a/?/>,,<*xbf> 


<“a/A/>,<Aa/"/>,,<*xc4> 
<*a/B/>,<*a/'/>,,<xel> 
<“a/B/>,<a/*/>,,<*xe5> 
<*a/A/>,<*a/A/>,<@> 
<*a/A/>,<a/E/>, ,<*xc6> 
<“a/A/>,<a/*/>,,<°xc2> 
<*a/A/>,<*a/_/>,,<*xaa> 
<“a/AB/>,<*a/*/>,_,<*xc0> 
<“a/A/>,<“al~/>,,<°xC3> 
<*a/A/>,<*x80>, ,<*xc4> 
<“a/A/>,<*xb0>, ,<xc5> 


<*a/C/>,<*a/,/>,,<*°xC7> 
<*a/C/>,<*a\/\>,,<*xa2> 
<*a/C/>,<“%a/0/>, ,<*xa9> 
<“a/C/>,<*a/O0/>, ,<*xa9> 
<Aa/C/>,<“a/|/>,,<*xa2> 


° 
, 


J 
a 


° 
e 
° 
r 


° 
‘ 


order sensitive 


order sensitive 


order sensitive 
order sensitive 


order sensitive 


~e we we 


VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 


VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VC$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 


VCS$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 


VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


Aw ‘N 


VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 


Default Three-Stroke Compose Table Values 


<“a/E/>,<“a/"/>, ,<*xcb> 
<Aa/E/>,<“a/'/>,,<*xc9> 
<“a/B/>,<*a/*/>,,<*xca> 
<Aa/E/>,<‘a/\/>,,<*xc8> 
<*a/E/>,<*x80>, ,<*xcb> 


<“a/I/>,<*a/"/>, ,<Axcf> 
<Aa/I/>,<“a/'/>,,<*xed> 
<Aa/I/>,<“a/%/>, ,<Axce> 
<Aa/I/>,<*a/*\/>,,<*xec> 
<“a/I/>,<*x80>, ,<*xcf> 


<“4a/L/>,<“*a/-/>, ,<*xa3> 
<*a/L/>,<*a/=/>, ,<*xa3> 


<Aa/N/>,<“a/~/>,,<°xdl> 


<*a/0/>,<a/"/>, ,<*xd6> 
<’a/0/>,<*a/'/>, ,<*xa3> 
<*a/0/>,<*a\/\>, ,<*xd8> 
<“a/0/>,<*a/C/>, ,<*xad9> 
<’a/0/>,<a/E/>, ,<*xd7> 
<*a/O0/>,<“a/S/>,,<*xa7> 
<“a/O/>,<“a/X/>,,<*xa8> 
<*a/O0/>,<*a/*/>, ,<*xd4> 
<*a/0/>,<*a/_/>,,<*xba> 
<Aa/O/>,<*a/\/>,,<°xd2> 
<*a/O0/>,<*a/~/>, ,<*xd5> 
<*a/O/>,<*x80>, ,<*xd6> 


<Aa/P/>,<“a/t/>, ,<*xb6> 


<“a/S/>,<“a/!/>,,<*xa7> 
<*a/S/>,<*a/0/>, ,<*xa7> 
<“a/S/>,<*a/O/>, ,<*xa7> 


<a/U/>,<*a/"/>,,<*xdc> 
<a/U/>,<“a/'/>,,<*xda> 
<Aa/U/>,<“a/*/>,,<*xdb> 
<a/U/>,<*a/*\/>,,<*xd9> 
<Aa/U/>,<*x80>, ,<Axde> 


<“a/X/>,<a/0/>, ,<*xa8> 
<“a/X/>,<“a/O/>, ,<*xa8> 


<“a/Y/>,<“a/"/>,_,<*xdd> 
<Aa/Y¥/>,<*a/-/>, ,<*xa5> 
<Aa/Y¥/>,<a/=/>,,<*xa5> 
<“a/Y/>,<*x80>, ,<*xdd> 


<a/*/>,<*a/ />,<*> 

<Aa/*/>,<a/./>,,<°xb7> 
<*a/*/>,<*a\/\>,,<*a/|/> 
<“a/*/>,<*a/0/>, ,<*xb0> 
<“a/%/>,<Aa/1/>,,<*xb9> 
<Aa/%/>,<*a/2/>,_,<*xb2> 
<Aa/*/>,<4a/3/>,,<*xb3> 
<4a/*/>,<*a/A/>, ,<*xC2> 
<*a/*%/>,<“a/E/>, ,<*xca> 
<Aa/*/>,<a/I/>,,<*xce> 
<Aa/*/>,<a/O0/>, ,<*xd4> 
<a/%*/>,<a/U/>, ,<*xdb> 
<*a/%/>,<“a/a/>, ,<*xe2> 
<a/4/>,<*a/e/>,,<*xea> 
<Aa/*/>,<“a/i/>, ,<*xee> 
<“a/*/>,<%a/o/>, ,<*xf4> 
<*a/%/>,<“a/u/>,,<*xib> 


order sensitive 


Default Three-Stroke Compose Table Values 


=e se Ne 


VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 


a to z 


VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_ KEY 
VCSCOMPOSE_ KEY 


VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VC$COMPOSE_KEY 


VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_ KEY 
VCS$COMPOSE_ KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_ KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


<Aa/_/>,<“a/A/>,,<xaa> 
<“a/_/>,<‘*a/O/>, ,<*xba> 
<*a/_/>,<“a/a/>,,<*xaa> 
<a/_/>,<“*a/o/>,,<*xba> 


<’a/\/>,<“a/A/>, ,<*xc0> 
<“a/*/>,<Aa/E/>, ,<°xc8> 
<“a/\/>,<Aa/I/>, ,<*xce> 
<“a/\/>,<a/O/>, ,<*xd2> 
<“a/\/>,<a/U/>, ,<*xd9> 
<*a/\/>,<“a/a/>,,<*xe0> 
<“a/*/>,<*a/e/>, ,<*xe8> 
<“a/\/>,<a/i/>,,<*xec> 
<“a/*/>,<a/o/>,,<*xf£2> 
<Ya/*/>,<a/ul>, .<*xf9> 


<“a/a/>,<a/"/>,,<xe4> 
<“a/a/>,<“a/'/>,,<xel> 
<*a/a/>,<a/*/>,,<*xe5> 
<Aa/a/>,<*a/*/>,,<*xe2> 
<“a/a/>,<a/_/>,,<*xaa> 
<Aa/a/>,<*a/\/>,,<*xe0> 
<“a/a/>,<*a/a/>,<@> 
<%a/a/>,<“a/e/>, ,<*xe6> 
<“a/a/>,<“*a/~/>, ,<*xe3> 
<a/a/>,<*x80>, ,<*xe4> 
<a/a/>,<*xb0>, ,<*xe5> 


<“a/c/>,<“a/,/>,,<*xe7> 
<Aa/c/>,<*a\/\>,,<*xa2> 
<“a/c/>,<*a/0/>,,<*xa9> 
<“a/c/>,<a/o/>, ,<*xa9> 
<*a/c/>,<“a/|/>,.<*xa2> 


<“a/e/>,<“a/"/>,,<*xeb> 
<“a/e/>,<*a/'/>,,<*xe9> 
<“a/e/>,<*a/*/>, ,<*xea> 
<“4a/e/>,<*a/\/>,,<*xe8> 
<“a/e/>,<*x80>,,<*xeb> 


<a/i/>,<*a/"/>,,<*xef> 
<a/i/>,<“a/'/>,,<*xed> 
<*a/i/>,<“a/*/>,,<*xee> 
<Aa/i/>,<a/\/>,,<*xec> 
<’a/i/>,<°x80>, ,<*xef> 


<“a/1/>,<‘*a/-/>,,<*xa3> 
<*a/1/>,<*a/=/>,,<*xa3> 
<a/1/>,<*a/*/>,,<*xb9> 


<Aa/n/>,<Aa/~/>,,<°xf1> 


<%a/o/>,<*a/"/>,_,<°x£6> 
<%a/o/>,<*a/'/>,,<x£3> 
<*a/o/>,<*a\/\>, ,<*xf8> 
<“a/o/>,<*a/*/>,_,<*xf4> 
<*%a/o/>,<*a/_/>,,<*xba> 
<Aa/o/>,<*a/*\/>,,<*xf2> 
<*a/o/>,<*a/c/>,,<*xa9> 
<“a/o/>,<a/e/>,,<*xf7> 
<“a/o/>,<*a/s/>,,<*xa7> 
<a/o/>,<*a/x/>,,<*xa8> 
<“a/o/>,<*a/~/>,_,<*xf£5> 
<%a/o/>,<*x80>, ,<*xf6> 


<“a/p/>,<“%a/!/>,,<*xb6> 


<4a/s/>,<“a/!/>,,<*xa7> 
<“a/s/>,<“4a/0/>,,<*xa7> 
<“a/s/>,<“a/o/>,,<*xa7> 
<“a/s/>,<a/s/>,,<*xdf> 


° 
f 


° 
‘ 


order sensitive 


order sensitive 


=e se se 


~e Ne Ne 


~e Ne Ne 


VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCS$COMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 
VC$COMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VC$COMPOSE_KEY 


Diaresis mark 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


Degree sign 


VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 
VCSCOMPOSE_KEY 


Default Three-Stroke Compose Table Values 


<a/u/>,<“a/"/>,,<°xfie> 
<“a/u/>,<“a/'/>,,<°xfa> 
<“a/u/>,<“%a/*/>,,<°xfib> 
<*a/u/>,<*a/\/>, ,<*x£9> 
<“a/u/>,<*x80>, ,<*xfc> 


<“a/x/>,<“*a/0/>, ,<*xa8> 
<Aa/x/>,<*a/o/>, ,<*xa8> 


<Aa/y/>,<*a/"/>,,<*xfd> 
<Aa/y/>,<*a/-/>,,<*xa5> 
<“a/y/>,<“a/=/>,,<*xa5> 
<Aa/y/>,<*x80>, ,<*xfd> 


<*a/|/>,<*a/C/>, ,<*xa2> 
<*a/|/>,<*a/c/>, ,<*xa2> 


<4a/~/>,<“a/ />,,<*a/~/> 


<*a/~/>,<*a/A/>, ,<*xc3> 
<“a/~/>,<“a/N/>,,<*xdl1l> 
<“a/~/>,<%a/O/>, ,<*xd5> 
<“a/~/>,<“a/a/>, ,<*xe3> 
<4a/~/>,<a/n/>,,<*xf1> 
<Aa/~/>,<*a/o/>,,<*xf£5> 


<*x80>,<“a/A/>,,<*xc4> 
<*x80>,<“a/E/>, ,<°xcb> 
<*x80>,<%a/I/>,,<*xcf> 
<“x80>,<*a/0O/>, ,<*xd6> 
<*x80>,<*%a/U/>, ,<*xdc> 
<*x80>,<“a/Y/>, ,<*xdd> 
<*x80>,<*a/a/>,,<*xe4> 
<*x80>,<*a/e/>, ,<*xeb> 
<“x80>,<‘a/i/>,,<*xef> 
<“x80>,<*“a/o/>,,<*xf6> 
<4x80>,<“a/u/>,,<*xfe> 
<*x80>,<“*a/y/>,,<*xfd> 


<AxbO>,<“%a/ />,,<*xb0> 
<“xb0O>,<*a/A/>, ,<°xce5> 
<*xb0>,<“a/a/>,,<*xe5> 


VCSCOMPOSE_KEYEND 


END THE TABLE 


H $QIO System Service Description 


The $QIO system service queues an I/O request to a channel associated 
with a device. The $QIO service completes asynchronously; that is, it 
returns to the caller immediately after queuing the I/O request, without 
waiting for the I/O operation to complete. 


For synchronous completion, use the Queue I/O Request and Wait 
($QIOW) service. The $QIOW service is identical to the $QIO service in 
every way, except that $QIOW returns to the caller after the I/O operation 
has completed. 


$QIO System Service 
$QIO System Service Description 
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$QIO SYSTEM 
SERVICE 
FORMAT SYS$QIO__[efn] ,chan ,func [,iosb] [,astadr] [, astorm] 
Lp1] Lp2] [,P3] [,P4] [,P5] LPG] 
RETURNS VMS Usage: cond_value 
type: longword (unsigned) 
access: write only 
mechanism: by value 
Longword condition value. All system services return (by value) a condition 
value in RO. Condition values that can be returned by this service are listed 
under ‘““CONDITION VALUES RETURNED.” 
ARGUMENTS efn 
VMS Usage: ef_number 
type: longword (unsigned) 
access: read only 


mechanism: by value 


Event flag that $QIO sets when the I/O operation actually completes. The 
efn argument is a longword value containing the number of the event flag. 


If efn is not specified, event flag 0 is set. 


When $QIO begins execution, it clears the specified event flag or event flag 
0 if efn was not specified. 


The specified event flag is set if the service terminates without queuing an 
I/O request. 


chan 

VMS Usage: channel 

type: word (unsigned) 
access: read only 


mechanism: by value 


VO channel that is assigned to the device to which the request is directed. 
The chan argument is a word value containing the number of the I/O 
channel; however, $QIO uses only the low-order word. 


func 

VMS Usage: function_code 
type: word (unsigned) 
access: read only 


mechanism: by value 


$QIO System Service 
$QIO System Service Description 


Device-specific function codes and function modifiers specifying the 
operation to be performed. The func is a longword value containing the 
function code. 


Each device has its own function codes and function modifiers. Refer 

to Chapter 3 and Chapter 4 for complete information about the function 
codes and function modifiers that apply to the particular I/O operation you 
want to perform. 


iosb 

VMS Usage: io_status_block 

type: quadword (unsigned) 
access: write only 


mechanism: by reference 


I/O status block to receive the final completion status of the I/O operation. 
The iosb is the address of the quadword I/O status block. 


The following diagram shows the structure of the I/O status block: 


31 15 ° 


transfer count condition value 





device-specific information 
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VO Status Block Fields 


condition value 


Word-length condition value returned by $QIO when the I/O operation 
actually completes. 


transfer count 
Number of bytes of data actually transferred in the I/O operation. 


device-specific information 


The contents of this field vary depending on the specific device and on the 
specified function code. 


When $QIO begins execution, it clears the quadword I/O status block if the 
iosb argument is specified. 


Although this argument is optional, Digital strongly recommends that you 
specify it for the following reasons. 


e If you are using an event flag to signal the completion of the service, 
you can test the I/O status block for a condition value to be sure that 
the event flag was not set by an event other than service completion. 


¢ If you are using the $SYNCH service to synchronize completion of the 
service, the I/O status block is a required argument for $SYNCH. 


e The condition values returned in RO and the I/O status block provide 
information about different aspects of the call to the $QIO service: 


- The condition value returned in RO provides information about the 
success or failure of the service call itself. 
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$QIO System Service 
$QIO System Service Description 


- The condition value returned in the status provides information 
about the success or failure of the service operation. 


Therefore, to assess accurately the success or failure of the call to 
$QIO, you must check the condition values returned in both RO and the 
I/O status block. 


astadr 

VMS Usage: ast_procedure 

type: procedure entry mask 
access: call without stack unwinding 


mechanism: by reference 


AST service routine to be executed when the I/O completes. The astadr 
argument is the address of a longword value that is the entry mask to the 
AST routine. 


The AST routine executes at the access mode of the caller of $QIO. 


astprm 

VMS Usage: user_arg 

type: longword (unsigned) 
access: read only 


mechanism: by value 


AST parameter to be passed to the AST service routine. The astprm 
argument is a longword value containing the AST parameter. 


p71 to p6é 

VMS Usage: varying_arg 

type: longword (unsigned) 
access: read only 


mechanism: by reference 
Optional device- and function-specific I/O request parameters. 


For more information on these parameters see the individual QIO 
descriptions contained in Chapters 3 and 4. 





DESCRIPTION 


$QIO operates only on assigned I/O channels and only from access modes 
that are equal to or more privileged than the access mode from which the 
original channel assignment was made. 


$QIO uses the following system resources: 


e The process quota for buffered I/O limit (BIOLM) or direct I/O limit 
(DIOLM) 


e The process buffered I/O byte count (BYTLM) quota 


e The process AST limit (ASTLM) quota if an AST service routine is 
specified 


e System dynamic memory is required to construct a data base to queue 
the I/O request 


e Additional memory may be required on a device-dependent basis 


$QIO System Service 
$QIO System Service Description 


To synchronize completion for $QIO, perform either of the following 


procedures. 


e¢ Specify the astadr argument with an AST routine execute when the I/O 


completes. 


¢ Call the Synchronize ($SYNCH) service to await completion of the I/O 
operation. (Because $QIOW completes synchronously, this is the better 
choice when you require synchronous completion.) 


astadr argument to have an AST routine execute when the I/O completes or (2) by calling the 
Synchronize ($SYNCH) service to await completion of the I/O operation. $QIOW completes 
synchronously, and it is the best choice when synchronous completion is required. 


RETURN | 

VALUES SS$_NORMAL 
SS$_ABORT 
SS$_ACCVIO 


SS$_DEVOFFLINE 


SS$_EXQUOTA 


SS$_ILLEFC 
SS$_INSFMEM 


SS$_IVCHAN 


SS$_NOPRIV 


SS$_UNASEFC 


Service successfully completed. The I/O request 
was successfully queued. 


A network logical link was broken. 


Either the /O status block cannot be written by 
the caller, or the parameters for device-dependent 
function codes are incorrectly specified. 


The specified device is offline and not currently 
available for use. 


The process has done any of the following: 
1. Exceeded its AST limit (ASTLM) quota 


2 Exceeded its buffered /O byte count (BYTLM) 
quota 


Exceeded its buffered 1/O limit (BIOLM) quota 
4 Exceeded its direct I/O limit (DIOLM) quota 


Requested a buffered I/O transfer smaller 
than the buffered byte count quota limit 
(BYTLM), but when added to other current 
buffer requests the buffered I/O byte count 
quota was exceeded 


An illegal event flag number was specified. 


Insufficient system dynamic memory is available to 
complete the service. 


An invalid channel number was specified, that is, a 
channel number of 0 or a number larger than the 
number of channels available. 


The specified channel does not exist, was assigned 
from a more privileged access mode, or the process 
does not have the necessary privileges to perform 
the specified functions on the device associated 
with the specified channel. 


The process is not associated with the cluster 
containing the specified event flag. 


$QIO System Service 
$QIO System Service Description 


SS$_LINKABORT 
SS$_LINKDISCON 


SS$_PATHLOST 
SS$_PROTOCOL 


SS$_CONNECFAIL 
SS$_FILALRACC 
SS$_INVLOGIN 
SS$_IVDEVNAM 
SS$_LINKEXIT 


SS$_NOLINKS 


SS$_NOSUCHNODE 
SS$_NOSUCHOBJ 


SS$_NOSUCHUSER 
SS$_PROTOCOL 


SS$_REJECT 
SS$_REMRSRC 


SS$_SHUT 
SS$_THIRDPARTY 
SS$_TOOMUCHDATA 


SS$_UNREACHABLE 


The network partner task aborted the logical link. 


The network partner task disconnected the logical 
link. 


The path to the network partner task node was lost. 


A network protocol error occurred, probably because 
of a network software error. 


The connection to a network object timed out or 
failed. 


A logical link is already accessed on the channel 
(that is, a previous connect on the channel). 


The access control information is invalid at the 
remote node. 


The NCB has an invalid format or content. 


The network partner task started, but exited before 
confirming the logical link (that is, $ASSIGN to 
SYS$NET). 


No logical links are available. The maximum number 
of logical links as set for the executor MAXIMUM 
LINKS parameter was exceeded. 


The specified node is unknown. 


The network object number is unknown at the 
remote node; or for a TASK = connect, the named 
DCL command procedure file cannot be found at 
the remote node. 


The remote node could not recognize the login 
information supplied with the connection request. 


A network protocol error occurred. This error is 
probably because of a network software error. 


The network object rejected the connection. 


The link could not be established because system 
resources at the remote node were insufficient. 


The local or remote node is no longer accepting 
connections. 


The togical link was terminated by a third party (for 
example, the System Manager). 


The task specified too much optional or interrupt 
data. 


The remote node is currently unreachable. 





CONDITION 
VALUES 
RETURNED 
IN THE I/O 
STATUS 
BLOCK 


Device-specific condition values. 
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I DEC Multinational Character Set 


Figure I-1 represents the ASCII character set (characters with decimal 
values 0 through 127), the first half of the DEC multinational character set. 


The first half of each numbered column identifies the character as you 
would enter it on a VT200 or VT100 series terminal or as you would see 

it on a printer (except for the nonprintable characters). The second half 
of each column identifies the character by the binary value of the byte; 
the value is stated in three radixes—octal, decimal, and hexadecimal. For 
example, under ASCII conventions, the letter uppercase A has a storage 
value of hexadecimal 41 (a bit configuration of 01000001), equivalent to 101 
in octal notation and 65 in decimal notation. 


Figure I-2 represents the second half of the DEC multinational character 
set (characters with decimal values 128 through 255). The first half of each 
of the numbered columns identifies the character as you would see it on 
a VT200 series terminal or printer (these characters cannot be output ona 
VT100 series terminal). 


DEC Multinational Character Set 


Figure I-1_ DEC Multinational Character Set—I 
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DEC Multinational Character Set 


Figure |-2_ DEC Multinational Character Set—Il 
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J ISO Latin Nr 1 Supplemental Character Set 


NOTE: 


The ASCII character set (characters with decimal values 0 through 127) 
comprises the first half of the ISO Latin character set. For example, the 
letter uppercase A has, under ASCII conventions, a storage value of 
hexadecimal 41 (a bit configuration of 01000001), equivalent to 101 in octal 
notation and 65 in decimal notation. 


The second half of the ISO Latin character set is represented as characters 
with decimal values 128 through 255. 


Characters in the first half of the ISO Latin character set can be output ona 
VT200 or VT100 series terminal. Characters in the second half of the ISO 
Latin character set cannot be output on a VT100 series terminal. 
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Absolute device coordinates 
See ADC 
ADC (absolute device coordinates) « 1-15, 2-26, 
2-32 
Alternate windowing system e 2-24 


Background color index « 5-19 
Bitmap 
accessing e 1-9, 1-11 
exclusive access to * 2-32 
loading into offscreen memory e 2-29 
loading into storage areae 1~11 
reading ¢ 2-28 
storage areae 1-11 
systemwide ¢ 4-17 
transferring © 1-11 
writing «© 2-28 
Bitmap IDe 2-29 
Bitmap_glyphs field « 5-21 
Bitmap_ID field e« 5-21 
Button simulation block e A-1 
Button transition value « 2-20 


C 


Channel 

assigning ¢ 2-2 

assigning to viewport e 2-25 

deassigning © 2-41 
Character 

composing nonstandard « 2-11 

input e 2-20 
Color 

displaying ¢ 2-46 

identifing system type ¢ 2-47 
Color map 

changing values ine 2-47 
Compose sequence e 2-11 








Compose sequence (cont’d.) 
three-stroke « 2-11 
two-stroke * 2-11 . 

Compose sequence table e 2-12 
constructing «© 2-12 
default * 2-16 
initializing « 2-15 
loading © 2-15, 2-16 
macro to generate « F-1 
terminating e 2-15 
three-stroke e 2-12 
two-stroke ¢ 2-13 

Control AST ¢ 2-3 

Cursor hot spot structure e« A-1 

Cursor pattern 
defining * 2-21 
multiplane « 2-22, 3-6 

Cursor pattern entry 
creating e 2-21 

Cursor pattern liste 1-12 

Cycling operation e 1-14 


D 


Data rectangle values blocke A-2 
Data structure 

using predefined structure * B-1 
DEC multinational character sete I-1 
Deferred queue e 1-18 

deleting ¢ 2-46 

executing © 2-46 





Define Pointer Cursor Pattern QlIOe 1-12, 2-21, 


3-3 
Define Viewport Region QIO e 2-26, 2-31, 2-33, 
2-46, 4-3 
Delete Bitmap DOP e 5-23 
Delete Deferred Queue Operation QiO « 2-46, 4—5 
Diacritical mark e 2-9, 2-11, 2-13 
Diacritical table e 2-13 
DOP (drawing operation primitive) * 1-6, 5-1 to 
5-81 
allocating memory fore 1-17 
allocating storage fore 5-3 
drawing with e 2-28 
entering on request queue e 1-17 
executing e 5-5 
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Index 


DOP (drawing operation primitive) 
executing (cont’d.) 
asynchronously e 5-5 
initializing « 5-9 to 5-14 
using predefined structure e 5-12 
large e¢ 5-3 
small e 5-3 
state of e 2-29 
structuring e 5-9 to 5-14 
using predefined structure e 5-12 
DOP Common block e 5-2, 5-10, 5-16 
initializing « 5-18 to 5-22 
DOP queue structure « B-1 
DOP Unique block 5-2, 5-12 
DOP Variable block e 5-2, 5-12 
Dop_line_array predefined structure « 5-41 
Dop_move_array predefined structure ¢ 5-52, 5-63 
Dop_move_r_array predefined structure * 5-24, 
5-56 
Dop_point_array predefined structure » 5-44 
Dop_poly_array predefined structure * 5-48 
Dop_structure predefined structure e 5-16 
Dop_vtext_array predefined structure ¢ 5-37 
Draw Complex Line DOP « 5-24 
Draw Fixed Text DOP « 5-28 
Drawing operation primitive 
See DOP 
Drawing to the QVSS screene 2-24 
Draw Lines DOP e 5-31 
Draw Points DOP e 5-34 
Draw Variable Text DOP « 5-37 
Driver differences 
alternate windowing e 1-3 
bitmap manipulation e 1-3 
colore 1-3 
driver interface e 1-3 
hardware interface e« 1-4 
UISDC interface * 1-3 
UIS interface e 1-3 


E 


Enable Button Transition QlOe 1-13, 2-18, 3-8 
Enable Data Digitizing QIO « 3-13 

Enable Function Keys QIO e 3-17 

Enable Input Simulation QIO « 3-20 

Enable Keyboard Input QIO* 1-14, 2-3, 2-6, 3-23 
Enable Keyboard Sound QIO e 3-29 

Enable Pointer Movement QlOe« 1-13, 2-17, 3-31 
Enable User Entry QIO e 3-35 — 
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Eventse 1-4 
Event tracking e« 1-12 
Example 
assign channele 2-4 
AST routine e 2-4 
keyboard requeste 2-4 
QVSS sample programe D-1 
Execute Deferred Queue QlOe 1-18, 2-46, 4-6 
Exit AST « 2-18 


F 


Fill Lines DOP e 5-41 

Fill Point DOP * 5-44 

Fill Polygon DOP « 2-41, 5-48 
Flags field « 5-22 

Foreground color index 5-19 
Free DOP « 1-17 

Free_1 areae 1-10, 2-31 


G 


Get Color Map Entries QIOe 2-48, 4-7 

Get Free DOPs QIO« 1-17, 4-9 

Get Keyboard Characteristics QlIO* 1-6, 3-37 

Get Next Input Token QIO e 2-3, 2-21, 3-39 

Get Number of List Entries QIO « 3-40 

Get System Information QlIOe 1-11, 2-1, 2-41, 
3-41 

Get Viewport ID QlIOe 1-16, 2-25, 4-10 


H 


Hardware color map ¢ 2-47 
determining current values of * 2-48 
loading values into e 2-48 

Hardware cursore 1-8 

Hardware look-up table e 2-47 

Hold Viewport Activity QlIO e 2-30, 4-12 











Image 
drawing e 2-29 


Image (cont’d.) 
storing © 2-29 
Initialize Screen QIO e 2-1, 3-42 
Input 
intercepting e 2-21 
Insert DOP QIO « 1-17, 2-30, 2-41, 4-13 
INSQUE (Insert Entry in Queue) instruction e 5-9 
Intensity value e 2-47 
Intercepting input e 2-21 
1O$C_QD_COLOR_CHAR function code ¢ 4-23 
lO$C_QD_DELETE_DEFERRED function code 
4-5 
lO$¢C_QD_EXECUTE_DEFERRED function code 
4-6 
1O$¢C_QD_GET_COLOR function code ¢ 4-7 
1O$C_QD_GET_FREE_DOPS function code e 4-9 
1IO$C_QD_GET_VIEWPORT_ID function code e 
4-10 
lIO$C_QD_HOLD function code « 4-12, 4-18 
1O$C_QD_LOAD_BITMAP function code « 4-14 
lO$C_QD_NOHOLD function code * 4-22 
1O0$C_QD_OCCLUDED_SUSPEND function code e 
4-28 
1IO$C_QD_RESUME_VP function code « 4-23 
lO$C_QD_SETCOLOR function code e 4-24 
10$C_QD_SET_VIEWPORT_REGIONS function 
code e 4-3 
1O$C_QD_START function code « 4-26 
1O$C_QD_STOP function code « 4-27 
1O$C_QD_SUSPEND_VP function code e 4-29 
1IO$C_QV_ENABLE_DIGITIZING function code 
3-13 
1O$C_QV_ENABUTTON function code e¢ 3-8 
lIO$C_QV_ENAFNKEY function code « 3-17 
lO$C_QV_ENAKB function code ¢ 3-23 
IO$C_QV_ENAUSER function code e 3-35 
10$C_QV_GETKB_INFO function code ¢ 3-37 
lIO$C_QV_GETSYS function code « 3-41 
1IO$C_QV_GET_ENTRIES function code « 3-40 
IO$C_QV_INITIALIZE © 3-42 
1O$¢C_QV_LOAD_COMPOSE_TABLE function code 
© 3-43 
1O$C_QV_LOAD_KEY_TABLE function code « 3-45 
IO$C_QV_MODIFYKB function code « 3-47 
lO$C_QV_MODIFYSYS function code « 3-51 
10$C_QV_MOUSEMOV function code ¢ 3-31 
lO$C_QV_SETCURSOR function code e 3-3 
1O$C_QV_SIMULATE function code « 3-20 
l1O$C_QV_SOUND function code e 3-29 
1O$C_QV_USE_DEFAULT_TABLE function code e 
3-55, 3-56 
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IO$M_QD_INTENSITY function modifier « 4-7, 
4-24 

1O$¢M_QD_RESERVED_COLORS function modifier « 
4-7, 4-24 

IO$M_QD_SYSTEM_WIDE function modifier e 4-14 

IO$M_QV_ACTIVE function modifier ¢ 3-47 

IO$M_QV_BIND function modifier e 3-3 

lOSM_QV_COMPOSE2Z function modifier e 3-55 

IO$M_QV_COMPOSES function modifier * 3-55 

lIO$M_QV_CYCLE function modifier ¢ 3-23, 3-35 

IO$M_QV_DELETE function modifier « 3-3, 3-8, 
3-13, 3-23, 3-31, 3-35 

lIO$SM_QV_KEYS function modifier « 3-56 

IO$M_QV_LAST function modifier « 3-3, 3-8, 3-23, 
3-31, 3-35 

lIO$M_QV_LOAD_DEFAULT function modifier « 3-3, 

3-43, 3-45 © . 

IO$M_QV_PURG_TAH function modifier * 3-8, 
3~23 

lO$_QV_TWO_PLANE_CURSOR function modifier e 
3-3 

lO$_QV_USE_DEFAULT function modifier « 3-3 

lO$¢_SENSEMODE © 1-5 

1O$_SETMODE e 1-5 

ISO Latin Nr 1 supplemental character sete J-1 

item_type field « 5-18 
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Key 
defining ¢ 2-7 
Keyboard 
activating e 1-14 
cyclinge 1-14 
poppinge 1-14 
programming ¢ 2-7 
receiving input frome 2-3 
usinge 2-3 to 2-16 
virtuale 2-4 
Keyboard characteristics ¢ 2-6 
defining ¢ 2-6 
Keyboard characteristics block e 2-4, A-3 
Keyboard entry liste 1-14, 2-3 
Keyboard request AST specification block « A-2 
Keyboard table 
constructing © 2-9 
initializing « 2-7 
loading e 2-7, 2-11 
macro to generate e E-1 
modifying ¢ 2-7 
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Index 


Keyboard table (cont’d.) 
terminating e 2-9 
Key-click volume « 2-6 
Keystroke AST specification block « A-5 


L 


LIBSGET_VMe 5-7 

List entrye 1-5, 1-12 

Load Bitmap QIO « 1-11, 2-29, 4-14 

Load compose sequence table e 2-16 

Load Compose Sequence Table QlO e 2-12, 2-16, 
3-43 

Load Keyboard Table QlO e 2-7, 2-11, 3-45 


Macro 
compose table e F-1 
keyboard table « E-1 
Mapping e 2-24.1 
Memory e 2-24.1 
offscreen e 1-7, 1-10, 1-16 
onscreene 1-7, 1-9, 1-16 
Memory usage 1-6 
Meta-key © 2-19, 3-9, 3-15, 3-24 
Modify Keyboard Characteristics QlO e 2-7, 3-47 
Modify Systemwide Characteristics QIO e« 2-6, 3-51 
Mouse e 2-18 
Move/Rotate Area DOP e 5-56 
Move Area DOP e 5-52 


N 


New cursor position structure A-8 


New pointer position structure e A-8 
Notify Deferred Queue Full QlO « 1-18, 2-46, 4-18 


O 


Occlusion e 1~—15, 1-18 

handling e 2-31 

handling with update regions * 1-16 
Offscreen memory e 1-7, 1-10, 1-16, 2-31 
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Onscreen memory ¢ 1-7, 1-9, 1-16 
Opcount field « 5-18 


p 


Plot_args predefined structure e 5-31, 5-34, 5-41, 
5-44, 5-48 
Pointere 2-18 
using © 2-17 
Pointer button characteristics block « A-6 
Pointer button transition * 2-17 
creating entry * 2-18 
Pointer button transition liste 1-13 
Pointer motion AST specification block e A-7 
Pointer movement ¢ 2-17 
creating entry® 2-17 
Pointer movement liste 1-13 
Pointer movement list entry * 2-18 
Pointer position « 2-20 
Popping operation « 1-14 
Pucke 2-18 


Q 


QDB (QDSS block) structure « B-3 
QDSS block 

See QDB 
QDSS Viewport ¢ 2-25 
QIO interface « 1-5 
Queue manipulation « 1-6 
QVB$L_MAIN_VIDEOADDR © 2-24, 2-24.1 
QVB$L_VIDEOADDR e 2-24.1 
QVB (QVSS block) structure « A-10 
$QVBDEF.MLB © 2-7 
Qvb_common_structure e A-10 
Qvb_qdss_ structure predefined structure « B-3 
Qv-DELETE ¢ 2-4, 2-18 
QV-LAST ¢ 2-17 
QVSS block 

See QVB 
QVSS control driver 

sample program e D-1 
QV_DELETE * 2-19, 2-22 
QV_LAST ¢ 2-19, 2-22 
QV_PURG_TAH e 2-19 
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Read Bitmap QIO e 1-11, 2-29, 2-33, 2-45, 4-19 
Regione 1-4 
defining « 1-5 
placing on deferred queue e 2-45 
Region descriptor * 2-18 
Release Hold QIO « 2-30, 4-22 
Request AST e 2-3 
Request queue e 1-6, 1-16, 5-6 
Req_structure predefined structure e B—1 
Reserved function keystroke AST specification 
block e A-14 
Resume Request Queue QIO * 2-30 
Resume Viewport Activity DOP « 2-30, 5-61 
Resume Viewport Activity QlIO e 4-23 
Return queue e 1-17, 5-4 
alternate « 1-18 
Return queue structure « B-5 
Ret_structure predefined structure « B-5 
Revert to Default Compose Table QIO « 2-16, 3-55 
Revert to Default Keyboard Table QIO « 2-11, 3-56 
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Scanline e 2-24.1 
Scanline mape 1-7, 1-8, 2-2, 2-24.1 
obtaining address of base * 2-24.1 
Screen 
drawing toe 2-24 
initialization « 2-1 
mapping video memory toe 2-24.1 
writing toe 1-6 
Screen event 
tracking e 1-12 
Screen rectangle values blocke A-14 
Screen saver time * 2-6 
Scroll areae 1-10 
Scroll Area DOP © 5-63 
Scrolling save areae 1-10 
Set Color Characteristics QIO « 2-47, 4~23 
Set Color Map Entries QIO e 2-47, 2-48, 4-24 
Set Viewport Region QlOe 1-15 
Source index e 5-19 
Start Request Queue DOP « 5-67 
Start Request Queue QIO e 2-26, 2-30, 2-33, 4-26 
Start Viewport Activity DOP e 2-30 
Stop Request Queue DOP « 5-69 
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Stop Request Queue QIO ¢ 2-30, 2-32, 4-27 

Stop Viewport Activity DOP « 2-30, 2-41 

Stop_args predefined structure « 5-61, 5-67, 5-69, 
5-70 

Stylus ¢ 2-18 

Suspend Occluded Viewport Activity QlIO « 4-28 

Suspend Request Queue QIO e 2-30 

Suspend Viewport Activity DOP e 2-30, 5-70 

Suspend Viewport Activity QIO * 4-29 

SYS$ASSIGN e 2-2 

SYS$DASSGN ¢ 2-41 

SYS$QIO ¢« H-2 

SYSTARTUP.COM e 2-24 

System characteristics block e 2-6, A-15 

System information blocke 1-6, 2-1 

Systemwide viewport e 1-15, 2-25 


T 


Text_args predefined structure e 5-28, 5-37 
Token e 2-19, 3-9, 3-15 
TPB (transfer parameter block) e 2-33, B-6 
Tpb_structure predefined structures B-6 
Transfer parameter block 

See TPB 
Type-ahead buffer 

getting input frome 2-20 

purging * 2-21 

using © 2-20 


U 


UISSCREATE_WINDOW ¢ 5-6 
UIS$WS_ALTAPPL e 2-24 
UISDC$SALLOCATE_DOP ¢ 5-3, 5-6, 5-12, 5-74 
UISDCS$EXECUTE_DOP_ASYNCH ¢ 5-5, 5-78 
UISDCSEXECUTE_DOP_SYNCH « 5-5, 5-80 
UISDC$LOAD_BITMAP e 1-11, 5-76 
UISDCSQUEUE_DOP « 5-5, 5-81 
Update regione 1-15 

and occlusione 1-16 

defining ¢ 2-25 
Update region definition 

See URD 
Update region definition blocks B-8 
URD (update region definition) buffer e 2-25, 2-31 
Urd_structure predefined structure e B-8 
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User-defined viewporte 1-15 


V 


VC$COMPOSE_KEY e 2-15 
VC$COMPOSE_KEYEND ¢ 2-15 
VC$COMPOSE_KEYINIT e 2-15 
VCS$KEY ¢ 2-7 
VC$KEYEND # 2-7 
VC$KEYINIT ¢ 2-7 
Video memory 
copying images toe 1-11 
drawing toe 1-11 
driver use of © 1-6 
mapping to screen e 2-24.1 
private ¢ 2-24 
setting bits ine 2-24 
Viewporte 1-4, 1-11, 1-15 to 1-16 
creating © 2-25 
defining ¢ 2-25, 2-26 
deleting « 2-40 
erasing e 2-41 
moving ¢ 2~45 
popping ¢ 2-31, 2-36 
redefining ¢ 2-31 
starting e 2-26 
- synchronizing activity one 2-29 
Viewport IDe 1-16, 5-6 
getting © 2-25 
Viewport-relative coordinates 
See VRC 
Viewport request queue ¢ 2-26 
Viewport update regions e 1-15 
VRC (viewport-relative coordinates) « 1-15, 2-26 
$VWSSYSDEF.MLB ¢ 2-15 | 


W 


Window IDe 5-6 
Windowing system 
alternate « 2-24 
enabling alternate « 2-24 
Write Bitmap QlIO e 1-11, 2-29, 2-33, 2-46, 4-30 
Writing mode e 5-19 
Writing mode field « 5-22 
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Z 


Z-mode e 2-46, 2-47 


VMS Workstation 
Video Device Driver Manual 
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READER’S Note: This form is for document comments only. DIGITAL will use comments _ 
submitted on this form at the company’s discretion. If you require a written reply 
COMMENTS and are eligible to receive one under Software Performance Report (SPR) service, 


submit your comments on an SPR form. 


Did. you find this manual understandable, usable, and well organized? Please make suggestions for improvement. 


Did you find errors in this manual? If so, specify the error and the page number. 


Please indicate the type of user/reader that you most nearly represent: 


Assembly language programmer 
Higher-level language programmer 
Occasional programmer (experienced) 
User with little programming experience 
Student programmer 

Other (please specify) 
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